Your task is to create a new repository for doing a tutorial project (of your choosing) and capturing your work step by step in that repository.
This will be your first chance to work closely with your mentor on a project.
Step 1: Create a new GitHub repository named ‘My first tutorial project‘. For the description use the title of this page: ‘Challenge: capture a tutorial project in a GitHub repository‘. Leave the default setting for Public rather than Private. Check the box to ‘Add a README file.’ Do not bother adding a .gitignore file. For ‘Choose a license’, leave it ‘None’. Finally, click ‘Create repository‘.
Step 2: Learn how to edit your new README.md file. You will notice that the list of files in your repository consists of the single file ‘README.md’. Below that will be a text area labeled ‘README‘, and it should already include the name of your repository and the description text.
Step 3: Near the top of the page, under the GitHub icon and your name, you will notice a line of tab labels. The first one is ‘Code‘ and that one will be selected automatically. After that is ‘Issues‘. Click on that. It won’t look very interesting at first because you have not created any issues. You should see a green button labeled ‘New issue‘. Click on that and you should see a page that lets you add a title and description for your new issue. In the area for your description, you will notice two tabs labeled ‘Write‘ and ‘Preview‘ with ‘Write‘ being selected. Under that is a text area. We will cover the features of this text area which are fairly extensive. But, for now just enter simple text. Type ‘This repository needs a good README.md file’ into the Title field and the description area. Then press the green ‘Submit new issue’ button. After that, you should see a more interesting issue page with a completed comment containing the description you just typed. Below that will be another text area where you can enter another comment. An issue is a list of comments that you and your mentor will write. It’s like a chat session about this issue. Finally notice to the right of the first comment a label ‘Assignees’ with a value of ‘No one-‘ and a link that will assign yourself as the person assigned to fix this issue. Do that now. Notice the changes to the page when you do that. You should see your name and picture appear in multiple places. Now that you have your first issue, you have assigned yourself the task of starting the README.md file. Finish this page by clicking on the ‘Code‘ tab a the top of the page.
Step 4. Invite your mentor to join you on this repository. At the very top of the page, you will see your repository title. Right click on that and in the drop down menu select ‘share…’. You will see a familiar dialog allowing you to share this repository via email, or other means. Select email and address the message to your mentor. Address your email to your mentor and ‘cc’ me: Mi**************@gm***.com. Enter an appropriate subject line, such as the title of your repository.
Step 5. Once your mentor has accepted your invitation you can begin working. First, you should edit your README.md file to describe the web development challenge you have chosen. While you can type just simple text into this file, the file extension of .md indicates that this file can contain Markdown, which is a lot more than simple text. You don’t need to learn all about Markdown, but a simple tutorial page is this one from w3schools.io: Markdown Tutorials.
Using markdown syntax you can indicate where your challenge comes from and why you chose that one. Make sure you include a link to the source of the challenge. You and your mentor can discuss what you hope to learn from this challenge.
There are many things that are appropriate for a Github repository README.md file, but that will come later.
Step 5. Start reading the instructions for your challenge. It should guide you through the process of setting up your project. Before you start the actual work, you need to use Github Desktop or one of the other similar programs. You can also choose one of the web development IDE programs that include GitHub support. VS Code is a popular choice. Using those tools, create a local clone of your repository so you have a working copy on your machine that you can edit, debug, and test the code you develop. Usually in challenges, the first step is to download a set of files that form the starting material. Go ahead and do that, but don’t actually start working yet.
Step 6. Using the tools in your IDE or other Git desktop program, commit the starting materials with an explanation code of ‘download starting materials’. Then push that to GitHub. This allows your mentor and anyone else to see your starting point.
Step 7. From this point forward, you should work in small increments. Read the instructions for a small amount of work, then create a new Issue in GitHub describing the requirements of that step and how you propose to implement it. At first you should take some time to think through what you are going to do and describe the changes you need to accomplish it. Assign that issue to yourself, but also include your mentor so that he is notified when you make new notes and especially when you commit and push changes.
Step 8. Use your tools, and reference to tutorial materials to implement the change you need to implement what is described in your new issue.
Step 9. Test and debug your new changes. If a test is more than trivial like just looking at your page in your web browser, you should write a test description. I suggest creating a ‘test’ directory inside your project, then create a text file to describe the step by step process of setting up and executing the test. This may seem too trivial but it is a very important step and will become much more important as your work progresses. Specifically, name the test file descriptively so that someone else can know what issue you were working on and what specifically you are testing. Your mentor is likely to want to use your test file to exercise your code when you push your changes for this issue.
Step 10. When you are confident you have addressed that issue, go ahead and commit and push. Make sure your commit message clearly indicates the issue being addressed. You will see later why that is important. When you do the push, you should also add a note to the issue so your mentor knows that you pushed a significant change that he should review.
Step 11. Review your work. When your mentor is notified of your update to the issue, he will be able to go to the GitHub project and see your commit. If you have not learned this yet, let me take a moment to describe it. With every commit, not only are the changes to the files pushed to GitHub, but in the Code tab, at the top of the list of files you will see an indication of the latest commit. It will give the name of the person, the explanation of the commit, and usually a link to the issue that is being addressed. Too the right of that, you should see the date of the commit. Finally, if there is enough room on the page, it should tell you how many total commits there have been. If you don’t see that, then grow the page or shrink the text until it appears. If you click on that, you will see a complete list of all commits. Take a look at one now, either in your project or any other GitHub project. Each item in that list is a link that will show you a list of all the files changed and an annotated portion of the source that was changed. Lines that were removed are highlighted in red with a ‘-‘ minus sign in the left margin. Lines added are highlighted in green with a ‘+’. Finally, notice at the bottom of the commit page there is another text box for you or more likely your mentor to comment on the changes you made. This can start a discussion where your mentor points out something you could have done different, or asks a question about why you made the change you did. This will be a very fruitful discussion, and you will learn a lot.
If you have done as I suggested and written a test case file, that should be included in the commit and the source will now be in the repository. Your mentor is likely to inspect that file and run your test. He may notice other problems, or perhaps pointed out good aspects of the way you made your change. This discussion is called a ‘Code Review‘. We will talk about those in a future lesson.
It is possible that your mentor may suggest yet another change either as an additional note in the Issue you were working on, or possibly he will have created another issue. If it is another issue, then you may be able to proceed with your work as planned, knowing that you have a new issue that can be addressed later in your process.
Step 12. If the code review was successful and your work was approved you should add one final note to the Issue page and rather than pressing the green Comment button, you can press the other button labeled ‘Close with comment’. That indicates that the issue is resolved. At this point, you can go back to Step 7 where you choose another small unit of work and create a new issue to discuss and resolve that work. This process continues until the whole project is complete.
Step 13. Finish your project. But, finishing requires one more step and that is to cleanup and complete your README.md file. First, read this article from FreeCodeCamp about ‘How to Write a good README File for Your GitHub Project.‘ It is especially important to do this step well. You will also want to put a link to your GitHub repository in your Upwork profile. It is important that clients considering you for a job be able to not just see a list of what you think you know, but to see an actual project that demonstrates your knowledge and skill. Having followed all the instructions in this challenge will ensure that a client can read your repository and see how you work. You will be demonstrating not only your skill in coding but also your professional discipline and teamwork. Make sure the README.md file is a good overall summary of your project.
Step 14. There will soon be a survey to complete showing that you have completed this challenge.