GitHub Process

I’m going to step outside of language agnostic features and talk a little about “process” in this article. Most companies have some sort of GitHub policy in place. However, sometimes they are not following guidelines that I believe work best. So, I thought I would list some of the GitHub policies that work for me.

First, my methods developed from git flow into trunk based development similar to how the linked article’s opening paragraph states. But, unlike just working off of master, I have a few other suggestions on the process. What seems to work best is the following:

1. Unit Tests. It just needs to be mentioned as number one. You want a high coverage rate, let’s say 85% which is low. Nobody will disagree that unit testing is important and should be done early. But, people rarely do. I find that you can tell the maturity of an engineer by how they approach unit testing.

• You want to make sure that unit tests passing is a requirement for a PR to be merged.
• You want to make sure your Unit Tests are relevant and don’t just mock everything.
• Code coverage should be part of every PR. Think of unit testing as you are developing to flush out your design.
• How about e2e testing? Is it done through unit tests? Maybe if you are a small shop. Otherwise, you need to think about how your e2e testing environment is going to run for CI.

2. Have a README and include code coverage tags and build tags.

3. Use semantic versioning. Tag your release and use major.minor.patch[-SNAPSHOT|beta|prerelease] (some use vX.X.X).

4. Start from master and forget about develop (trunk-based development).

5. The idea is to keep the master branch as “always the main source of truth.”

6. When you have to create new releases:

• Start with a tag (you can always branch from a tag later).
• Have your CI pick up on a release tag and follow the release cycle. This should not be just an easy nod and dismiss. This flow makes it real easy to tag releases and you can be explicit on whether it is a snapshot, a beta or a release.
• Use a CHANGELOG and basically, copy what is there for the release you are releasing. If you can be extra detailed, add the fix/feature along with the link to the PR.

7. Once you have to create a branch off of a tag for patches:

• Your new branch should be whatever your latest major and minor are followed by X (e.g. 1.1.X). This branch applies to 1.1.0–1.1.9 with the idea that you can always branch from there for the next release if you can no longer use master. But, the point is to always go back to master as the latest release.
• If you can, apply the fix to master first and then cherry-pick to your branch. There may have to be several cherry picks if you have to patch multiple branches and they could be based off of something other than master (such as the original 1.0.X branch).
• Drive your customers to the latest release whenever possible.

8. ICs (individual contributors) should create a branch off of master or whatever major minor branch they have to apply this to if it can’t be applied to master (always cherry-pick from master if you can).

9. You should always create a PR and have it reviewed. If you have a team, have them review it. If not, review it like it was written by someone else and sit on it for a day mull it over. Don’t be a jerk or too nit picky but if you can think of anything to add, it is a great time to add it.

10. The PR should normally be against master but even when applying cherry-picked fixes, they should also be done in a PR for review.

11. Use slack and/or email hooks for github updates.

12. Use github issues even if you use something else for bugs, features, or stories. It is a little more in your face and you can alway reference your jira ticket (there I said it).

13. GitHub pages are great for docs (start docs early).

Having said all this, I can’t really recommend a CI or code coverage tool for you. I’ve used Travis, Jenkins, and CircleCI for builds. They all have their pluses and minuses. I lean toward one more than the other but I will leave that up to you to decide. It is pretty easy to add a stage for releasing off a tag in whichever integration environment you chose.

I’ve written all this as a starting point on the discussion of repo process. I think it’s important to be as verbose as possible on these types of processes. I hope that you find this useful. Happy Coding!