How to create or update a readme from a forked repo on your own repo- 034

I love writing about code, so it pains me whenever I don’t see instructions how to get started. Let’s say you are like me and you want to add a readme to a project you’ve forked. This tips covers how to commit your new README.md file to your local repo first, so then you can propose it to the original repo. That’s how GitHub works.

Navigate to your forked copy, e.g. saraford-tips/your-moment-of-github-zen that I’m using for this demo. (the original repo is at saraford/your-moment-of-github-zen. Perhaps I should have used a more distinguishable name for these tips, sigh.)

At the bottom of the files listed you’ll see a button to Add a README. Clicking this button will automatically create a new file called README.md, as if you had manually clicked the Create new file button yourself.

Click Add a README at bottom

Clicking the Add a README button brings you to the README.md new file page.

Enter some instructions and make sure to preview for any Markdown formatting typos!

install instructions preview in readme.md file

After your proposed readme looks the way you want, you’ll scroll down to the Commit section and fill out the information about the commit accordingly. Note that in the below image, I selected a new branch for this commit and I renamed the branch to created-readme.

It is a matter of convention whether you commit to master or commit to a branch. Both are technically possible (doing a PR from master or doing a PR from a branch), but it is more of a social coding norm to commit to a branch. The idea is that master should always be your last known good, stable release. Proposed work or work in progress should be made on branches.

Create a new branch selected in commit form

Now click propose new file.

You haven’t actually “proposed the new file” yet. All you have done is committed the new README.md file to your local repo.

The GitHub workflow here is designed for someone who wants to submit the Pull Request immediately, but you don’t have to submit the Pull Request right now. Suppose you need to go back and make some edits. You’ve seen in previous tips that you can cancel out of this Pull Request form (by navigating anywhere else away from this page) and making any necessary edits on your created-readme branch.

I’ll pause this tip here. My style is to have these tips as short and to the point as possible about what each piece of functionality does, rather than how to use each piece of functionality in end-to-end scenarios.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s