Using GitHub for the first time has a steep learning curve. To use GitHub with a team is a whole different ball game. Here are some best practices I’ve come to know during my team projects.
Throughout the various OSS projects that I contributed to one thing always takes up more time than I expect. Setting a Git(Hub) standard for working on a repository (or repo as the cool kids say it). Below are some best practices that really helped me along the way.
Protect your branches
The first thing that prevents headaches in the future is to protect the
master branch and make a
develop one right away. It disables force pushing and prevents branches from being deleted. A great way to protect you’re project and make sure that you don’t have to 🚑 hotfix anything if you use continuous integration for example.
Consistent branch naming
master branch protected contributors can’t push straight into
master. They have to use branches and make
pull requests. Coming up with a naming convention for the branches is very helpful. One of the things is to use prefixes:
In a quick overview you can see what each branch is for and they have consistent naming.
Make sure PR’s can’t be merged without a required review. If you protect a branch you can also enable
Require pull request reviews before merging. Every PR that comes in has to be reviewed by another contributor.
So, merging is blocked by default. A contributor has to manually navigate to the PR and hit
review changes. You then can either:
- Make comments for general feedback. (No explicit approval)
- Approve the changes and the PR can be merged
- Request changes, things that have to be fixed before merging.
A great way to get a quick quality check before the code get merged.
- It keeps the overall quality of the code on point.
- More eyes 👀 are better. Somebody else can spot a mistake you might have missed.
- And personally, I think it’s a good way to learn by looking at somebody else’s code.
Oh god, commit messages. Always a painful topic to talk about. Everyone has a personal / preferred way to do it. Chris Beam has written a great post about this in 2014. It are some general rules but most people find them acceptable.
You should definitely read the full post.
Ideally your commit title would look like this:
Add styling for navigation bar
Usually these rules are outlined in the
contributing.md and examples are given.
Plan your commits
Guilty as charge of commiting a large blob of code. But, planning your commits is also a good strategy to keep yourself in check. Before you go straight into building that feature try to break the feature down into small steps. Each step then represents a commit. Here is a quick little post on dev.to about this.
Coming up with a consistent GitHub standard and flow may take some time but it’s worth it in the long run. It makes the repo far more maintainable and has saved me from panic situations.
Thanks for reading! You can follow me on @dandevri and feel free to reach out to me if you have something to say!