Learning Best Practices for Open Source

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

Commit Messages

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.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples

A simple commit message following Conventional Commits looks like this

feat(parser): enable x to do y perfectly

Parameters

  • type: Type of commit. Can be one of the following fix, feat, build, chore, docs, style, refactor, perf, test etc.
  • 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

Merging Branches

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

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

Recursive Subtypes

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 ours & theirs can take you a long way. Here’s how I use them

git merge -X ours development

or

git merge -X theirs development

Example Please?

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 master

git merge -X theirs dev

We’re trying to merge the dev branch into master. 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

Releases

Resources

I’ll be learning and updating this list as times goes on