I opened my first Github issue this week. It got me thinking about the way I currently use github…
My usage of Github has changed rapidly in the past few months. Majorly because we now have a more structured team/workflow at work.
There’s times when things go far north (Like burying colleagues’ days of code in merges😂, etc).
I’ve decided spend a moment to learn best practices for organizing code and collaborating with other engineers. My goal is to keep this as an evergreen note and update with more information as I learn more.
I like to think of open source best practices in these aspects
Looking through commits to popular open source projects left me confused about which convention to follow. The Bootstrap contribution guide points to a very old article - A Note About Git Commit Messages which I think is the base for other newer and more refined conventions
After a few hours of researching, I stumbled on one that made all the sense I wanted. Enter Conventional commits.
The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
You can go through Conventional Commit’s website for a more detailed overview, as this article scratches the surface.
<type>[optional scope]: <description> [optional body] [optional footer(s)]
A simple commit message following Conventional Commits looks like this
feat(parser): enable x to do y perfectly
- type: Type of commit. Can be one of the following
- optional scope: Scope of the commit. Helps narrow down
- description: A short description of the commit
- optional body: A more detailed description of the commit
- optional footer:
Working With Branches
I don’t have any experience contributing to open source projects, but the processes I’ve seen resemble this…
- Fork the project
- Create a branch for your changes
- Send a pull request to the origin
- Your changes are reviewed and merged (if accepted)
That’s all I know. I’ll update this section as I learn more about pull requests
I recall a time at work. We had the
master diverge from the
development branch. Everyone was literally afraid of merging because that would normally take the entire day and people’s hours of code would be buried.
I’m glad that time is over and we can now navigate merging without loosing our minds. Merging branches was easier for me once I learned about merging strategies
It was hard to accept that resolving merge conflicts meant manually accepting/rejecting incoming changes. With merging strategies, we can choose which branches should have the highest priority when conflicts occur.
There are 3 basic merge strategies
- Recursive: Default for 2 heads while pulling from or merging a branch
- Resolve: Recursive, except more carefully
- Octopus: Default strategy for more than 2 heads
- Ours: Ignores changes from other branches in favor of the current branch
- Subtree: Strategy for branches with multiple children levels
You can modify the default (Recursive) merging behavior by using any of the following subtypes
- ours, theirs, patience, diff-algorithm, renormalize, no-renormalize, no-rename, find-renames=n, subtree
There’s no need to know how all these work. Knowing to use just
theirs can take you a long way. Here’s how I use them
git merge -X ours development or git merge -X theirs development
Let’s say I have a
master and a
dev branch. I write all the code on the
dev branch and recently want to merge my changes into master. I could just do
git merge dev (On
master branch) and git will use the default algorithms to merge code where necessary.
Or I could want the changes from the
dev to overwrite same files in the
git merge -X theirs dev
We’re trying to merge the
dev branch into
Theirs here refers to the
dev branch and we want git to take changes from
dev as a priority. If we do the opposite
git merge -X ours dev
We’re telling git to take ours (
master) as priority and if there’s a
Merging Strategies is a complex topic on it’s own, so I recommend reading this guide
I’ll be learning and updating this list as times goes on
- Best Practices for Using Open Source Code
- Best practices for open source software
- Tips for New Open Source Maintainers
- 7 Best Practices for Managing Open Source Components
- Best Practices for Maintainers
- Best practices for Open Source Software Contributions
- Semantic Release
- Git Commit Guidelines
- A Note About Git Commit Messages
- Merging Strategies is a complex topic on it’s own