Tag: pull requests

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.

How to search for a Pull Request based on a branch name – 025

In yesterday’s tip, it was easy to find the desired Pull Request when there’s only been one Pull Request created. Today, let’s say that you want to restore a deleted branch, but you need to search for the Pull Request to get to the Restore button. Deleted branches aren’t shown on the Branches page.

Navigate to the Pull Request tab, and in the search field, 1. delete the search defaults and 2. type in

head:<branch-name>

Notice you’re using head: as the search parameter because there are two branches involved in a Pull Request. The base branch is the branch that the changes are going into. The head branch is the source of those changes.

searching pull requests for head:readme-draft

And in the above screenshot, you see the Updated the readme PR that contains the readme-draft.

You can also search based on base branch using the base:<branch-name> search option. Check out the search documentation for more information.

How to restore a deleted branch that is associated with a Pull Request in your repo – 024

Suppose you want to restore a branch that’s been deleted after you merged a Pull Request. (TBH: I’m not sure under what conditions you want to restore a branch that’s been merged. If you need to make more changes, my guess would be to create a new branch and a new Pull Request. I’m curious to hear other’s thoughts in the comments.)

But when you go to your list of branches by clicking the Branches link above the repository language bar

branches link above repository bar

You’ll find that your recently deleted branch (e.g. readme-draft) isn’t listed.

list of all branches

Since the readme-draft branch you saw me delete from the previous tips is tied to a Pull Request, you can navigate back to that Pull Request (make sure you search for closed Pull Requests!!)

searching for closed pull requests

and now you’ll see the button to restore the deleted branch.

Restore the delete branch button on closed pull request

Clicking on Restore branch button takes you right back to where you were at in the Pull Request before you deleted the branch, with the exception of history that you’ve restored the branch.

image

You’ll also see the branch come back in the Branch:master dropdown switch button.

Branch dropdown switch button showing readme-draft again

How to tidy up after merging a Pull Request in your own repo – 023

Following yesterday’s tip, after a Pull Request has been merge, you’ll see a message suggesting that you delete the target branch.

Pull request successfully merged and closed - the readme-draft branch can be safely deleted

But why would I want to delete this readme-draft? What data do I lose if I delete it?

First, let’s talk about this possible data. The data around the conversation was captured as part of the Pull Request, which was only closed (not deleted), so you can still find it on GitHub.

Merged pull requests are considered closed when searching

Second, the data around the commits was merged into master, so that’s not being lost. Stay tuned to the end of this blog post to see a screenshot of these commits sticking around after I delete the branch.

Third, you most likely won’t need to use this branch again. Over time, as your number of merges increases, you’ll have a long list of branches.

switch branches dropdown using a scrollbar to list all branches

Hence it is considered good practice to clean up after your pull requests.

Fourth (and probably most importantly), this is a fundamental difference in how Git works compared to other source control systems. Branches are just pointers to a snapshot in time. More on this in upcoming tips when I start to play with Git command line concepts.

Lastly, you can always restore! Stay tuned to tomorrow’s tip.

Let’s delete this readme-draft branch. Click on the Delete branch button, and volia!

deleted the readme-draft branch message

And you can look a few lines up and see that the Pull Request still contains all the commits, regardless that the branch was deleted.

commits are still listed in the Pull Request after merge