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.

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!

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.

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.

• Git(Hub) Tip of the Day 2017