A guide for infrequent contributors to Racket

Maybe you want to contribute something to Racket: You’d like to improve the documentation, or you’d like to add a small feature.

Maybe you’re comfortable with Git, but haven’t made a pull request before.

Maybe you’ve made a one-off pull request, but haven’t tried to contribute to the same project over time and stay in sync with the upstream project.

If so, you may find my guide helpful. I was hopelessly confused about how to handle the branches and merging. After I figured it out, I wrote this down in a Gist as a note to my future self. Today I figured I’d dust it off and make it into a blog post.

Hack, hack, hack

Prepare your topic branch for the pull request

Maybe you like to commit often as you work on a feature. I do. It’s a form of backup and a paper trail. That’s great, but preferably your pull request should be just one commit. Easier on the maintainer. Plus the upstream project doesn’t need 20 commits in its history for your 1 feature.

You should rebase your topic branch on the upstream master, to catch any changes or conflicts.

Push your topic branch to GitHub

The point of the -f (force flag) is in case you had already pushed this topic branch. After you use rebase (above), you’ll probably need to force the push.

Note: Using push -f is usually bad. Here it’s OK because we’re push -f-ing to a topic branch in our forked repo that no one has pulled from yet.

Make your pull request on GitHub

Visit your forked repo’s page on GitHub.

If you recently pushed your topic branch, you’ll see a handy button to make a pull request for the branch:

Recent pushed branch

You can also use the main Pull Request button.

Either way, you get the Pull Request page:

Pull request page

The pull request page has three “tabs”:

New Pull Request. This is a title and description. The title defaults to your commit message’s first line. The description defaults to the rest of your commit message. (If you have more than commit, you won’t have these defaults. But as described above, you really shouldn’t include more than one commit in your pull request.)

Commits. Preferably this should have the number 1 next to it — just one commit in your pull request. You should click the tab and double-check that the commit is what you expect.

Files Changed. Again, double-check to make sure it looks correct.

When all looks good, click Send Pull Request.

Waiting is the hardest part

What next? You wait for your pull request to be accepted and merged. Then it will flow back to you when you do git pull --ff-only
upstream master, because your commit is now part of the official plt/racket repo.

But it might take awhile for the pull request to be accepted. It might never be accepted.

In the meantime, you might be tempted to merge your topic branch into your own master. Don’t!

If you were to do that, your master would cease being a nice clean mirror of the upstream master. Remember how no one likes a dirty fork, so we’re diligently using git pull --ff-only upstream master?

So the simplest thing to do is just wait.

But if you really want to use your feature, in your own custom build, I suggest making some other branch (e.g. custom-build). Feel free to merge from your topic branches (and from upstream master) into that branch, from which you can build your custom variation of Racket.

Just remember that topic branches for pull requests should still always be based off your master, which should be a fast-forward mirror of upstream.