Introducing GitHub Repositories: Modifying README.md

I highly recommend that every project, whether public or private, have a README.md file at the top level. This file is often the starting point for anyone who wants to contribute to the code.

The README.md file will often have the following sections:

» Project title and description

» Prerequisites for getting the project running on your local machine

» Instructions on installing the project (and any dependencies)

» Instructions on running tests to make sure that you haven’t broken anything

» Instructions on deploying the project

» An overview of dependencies

» A link to the guide on how to contribute to the project, including a code of conduct

» The main authors or maintainers of the project

» A link to the license » Any additional acknowledgements

PurpleBooth on GitHub has created a great template for a README.md at https:// gist.github.com/PurpleBooth/109311bb0361f32d87a2.

GitHub promotes a culture of sharing and open software development. In the sharing, it is important that each person acknowledge where they drew inspira­tion and what pieces went into helping them create what they have created. Soft­ware development rarely happens alone and, at this point, is always built on someone else’s work. Though you don’t have to specifically acknowledge the work that Grace Hopper, a well-known computer scientist who created the first com­piler and English programming language, did to promote high-level program­ming languages so that you’re not all writing in assembly anymore, you should always recognize that it’s a large, timeless community working toward building, creating, and pushing the boundaries of what you think is possible today.

For simpler projects, a README.md file can also be the front page to your project. In this case, the project is a description of you, and the README.md file is essen­tially the entire project because it will contain the information about you!

Follow these steps to modify your README with a headshot and a short descrip­tion about things you love:

1. Go to the Code tab of your repository and click the Upload files button.

Steps 2 through 6 guide you through the page shown in Figure 3-5.

2. Find a headshot of yourself (or any picture that you want to be on your README) and upload it using the drag box.

Alternatively, you can click the Choose your files link and browse your files to find your photo.

3. Type a title in the text box Commit changes.

In this example, I added the title “Adding a Headshot.”

4. Select Create a new branch for this commit and start a pull request.
5. Type a name for the branch, or you can leave the default name for the branch.

I left my default name, which is sarah-wecan-patch-1.

6. Then click the Propose changes button.

The Open a pull request page appears with your one commit to add a new headshot to your repo (see Figure 3-6).

7. Add a short description to explain the change and then click the Create pull request button.

The Pull request tab displays your pull request with a title, number, status, description, list of commits, and a check to see whether it can be merged with master, shown in Figure 3-7.

8. Click the Code tab to go back to the code in your repo.
9. Click the branch drop-down list and switch to the branch you created in Step 5.

This step allows you to see your project as it looks in that branch. The changes you make added to that branch as you make them and therefore the pull request that you created in Step 6. That way, you can add your headshot and make all the changes to the README at once.

You see the new branch you created. Next to the branch is a link to the pull request you created. This branch is associated with that pull request, so you can kind of think of them as the same things. You also see the picture that you uploaded in your list of files.

10. Because your README file is still showing, click the little pencil so that you can change what the README says. If it exists, a README file always appears below the list of files.
11. Using Markdown, write a little about yourself, including your career passions and some hobbies you enjoy. Figure 3-8 shows you an example of the type of information you may want to include.
12. Click the Preview changes tab above the text. A red line appears to the left of the first two lines to indicate they will be deleted (see Figure 3-9). Everything you wrote after that has a green line to the left of it to indicate that the text will be added to your description.
13. When you’re satisfied with your description, scroll to the bottom of the file editor, add a title to the commit, and commit to the same branch you just created.

You see your README.md file in its final state.

14. Click the HelloWorld link at the top where it says HelloWorld/README.md to return to your code home page.

15. Add your headshot by clicking on the pencil above the README.md file and adding the following line:


Make sure that you put the name of your picture in place of sarah_pic.jpeg.

16. Preview the changes.

Your headshot now appears. You can see mine in Figure 3-10.

17. Scroll to the bottom and commit your changes.

You have now made changes to your project. The only problem is these changes are still on their own branch, and not on the master branch. To find out how get your changes merged into the master branch, refer to the next section.

Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.