Tag: readme

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.

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.

How to show user documents and other content (readme) at the bottom of your GitHub repo homepage – 016

One of the biggest concepts I had to learn when using GitHub.com the first time is that the much of the repository metadata comes from content within the repo files themselves. To illustrate, back in the day on CodePlex, your license and homepage content were stored as part of the CodePlex project, instead of being generated based on the contents of your repository. Once I made this mental switch, GitHub got a lot easier to use. And FWIW, as I learned in UX grad school, it’s much, much easier to learn a new skill than it is to unlearn an old skill to learn new similar skill.

And what I mean by the title of this post is the content that appears at the bottom of the list of files in your repo. E.g. the electron/electron-api-demos shows a few lines of text and then an image, and then the rest of the readme file.

And yes this is a possible duplicate of #003, but if you don’t know this content is coming from a README.md file, you won’t know you need to add a README file. I felt it important to include these points of view.

Let’s say that you did not check the Initialize this repository with a README checkbox when you first created your repository.

You’ll won’t see the default generated README.md content (which is just the name of your repo and the description, if you provided one).

These days, you’ll see a nice information box encouraging you to create a README.

If you click this button, you’ll be taken to the familiar “Create a new file” UI on GitHub, where it creates a new README.md file. If you use all the provided defaults, you’ll get the same generated README file as if you had checked the Initialize this repository with a README button on the new repository page.

How to add a Readme to a newly created repo if you forgot to check the Readme box – #003

I can’t tell you how many of times I’ve wanted to quickly setup a new repo to add some files directly to it via the UI (see yesterday’s tip), but I forgot to click the Initialize this repository with a README checkbox on the /new page.

If you’re like me and you’ve realize you forgot to check the checkbox, you can add the file by clicking the README link in the list of recommended files.