There are some neat tricks you can do to improve your life on GitHub, – and when using git – as well as the lives of those around you. I wanted to showcase some of them here. Let’s start with a browser extension.

GitHub Linker

This browser extension allows you to navigate across CommonJS require calls and package.json declarations simply by clicking on the linkified names of the packages. It’s quite convenient.

Naturally, you can get it on GitHub.

Squashing Commits

One of the first things I’ve learned when I started doing open-source was to squash my commits. Open-source folk like their commit logs clean and readable, a searchable and meaningful history of their repository. Squashing means turning a lump of commits into a single commit. This is one of the things almost every maintainer out there asks you to do before merging your PR, and you can quickly understand why.

Suppose you’ve created two commits and submitted a PR against a repo you like, closing a bug you’ve filed a few hours earlier. The maintainer does some code review, asks you for a few changes, you commit some more. Now the PR has 5 commits, some of which undo work you did in the first few commits. Merging this PR as-is would add a ton of different commits for only one unit of work – that is, fixing a single bug. Squashing the commits together improves readability of the changelog, and linkability of commits when referring to an individual bug fix.

To squash your latest commits, suppose there’s 5 of them, you can run the following commands:

git reset HEAD~5
git add .
git commit -am "Here's the bug fix that closes #28"
git push --force

After running git reset, all your work will be unstaged, so you can then create another commit. This will rewrite history in the branch for your PR, but that’s okay because nobody depends on that until it gets merged. And when that happens, only one commit will be pulled by everyone else!

Amending your commits

If you want to change your latest commit before pushing – because your commit message was a placeholder like “foo” – you can use --amend, like so:

git commit --amend -m "Some other commit message."

If you had already pushed, you can still ammend the commit, but then you’ll have to force-push. Again, beware, this rewrites history in git, so it’s best to avoid force-pushing when possible.

git push --force

In line with squashing and amending commits, we should also take care of thoughtful commit messages.

Commit Messages

The message in a commit should be descriptive enough to summarize the entire changeset. A good commit message might be "fixed #18, where a dialog box would pop up in the wrong place", not so long that it becomes distracting, and not so short that it doesn’t tell you anything about what was changed.

Something like "foo" is a terrible commit message. At that point, you might as well just create a commit with an empty message. This might be useful in those situations where you just want to redeploy to trigger another build in a CI system, without visiting their web interface.

git commit --allow-empty

Let’s move on. What makes a good issue or pull request?

Issues and Pull Requests

When it comes to creating an issue, you’ll find that maintainers are much more welcoming if you’ve put any effort beforehand. That entails:

Reading documentation about their library
Figuring out if the issue has been already reported
Taking the time to isolate the issue and provide precise bug reports
Providing screenshots or reproduction steps

If you do at least one of the above, your reports will be taken more seriously and probably addressed more swiftly. If you don’t “have the time” to do research around the issue you’re reporting, why would maintainers spend theirs fixing your issues with their library?

While yes, it’s in their best interest to fix broken things, it’s also nice to see contributors who actually go through the motions of at least trying to make things easier for the maintainers.

When it comes to pull requests, try and match the code style used in the repository you’re contributing to. If they have a CONTRIBUTING.md file, that’d be a good place to learn about how they want you to approach contributions. Matching their coding style will save you a lot of time in back and forth, git commits, and amendments. Plus, maintainers will be grateful for it!

Above all, be nice. Most of us do open-source just because we like the “sharing mentality” in OSS, because we value the effort that others invest in open-source, or simply because we enjoy it. For most people however, it’s not their day job, but something they do on their spare time. Even when it is, they don’t owe you anything, so don’t make demands.