haykot.dev
Python Git

August 14, 2021

Lessons From a Rewrite: Improving Your Git Workflow

This article is the first in a series discussing the rewrite of Mealie. During the process, I’m taking time to reevaluate some of the choices and workflows I’ve adopted over the last 8 months and refreshing some that aren’t quite working. In this article, I’ll be looking at how and why my current git workflow is failing me and other contributors and look forward to a new process for contributing.

Current Workflow

The current workflow for all releases is to work in a 3 branch process. There are two “main” branches, master and dev and various feature branches.

  • The master branch is used as a snapshot of the current latest release.
  • The dev branch is used for staging features and coordinating developer work.
  • The feature-* branches work as a staging ground for PRs that come into the dev branch

To contribute, users typically fork the dev branch, conduct their work, and merge back to dev. When it’s time for release I’ll create a PR from dev to master and merge all the changes into master, create a release, and off we go.

The Problems

While this process may work well for extremely coordinated teams, It’s been difficult to keep straight in an open-source project. Some of the problems I’ve run into

  1. Contributors often work master and work from there causing conflicts on PRs
  2. master and dev can get too far out on sync and be difficult to merge
  3. Can’t update documentation apart of the master without merging all of the changes from dev.

The Updated Workflow

As I’m conducting the re-write in the mealie-next branch. I’ve been working out a new process for how to make contributing easier and more simple. The big question around this is, What value does a release snapshot branch have? I think there are two main benefits ****

  • The master branch offers users a cloneable repo to build from directly
  • It makes it easy to inspect the source code of the latest public release.

I don’t think either of these reasons justifies increasing complexity for contributors. I use GitHub actions to publish docker-containers for users to deploy from, building from the source likely isn’t a common use-case. If they did want to build from the source or inspect the release code, It’s entirely possible to get that source code from the GitHub release itself.

The Solution

Moving forward once mealie-next is ready for contributions we will adopt the following workflow for contributors.

  1. The main branch will serve as the sole working constant branch in the repo.
  2. All feature branches will be forked from main and merged directly into the main branch.
  3. Releases will be made directly from the main branch.

Additionally, we’ll be including some more detailed guidelines in our contributor’s guide.

  1. We’ll be following the Conventional Commits style
  2. Feature branches should be short-lived and condensible to a single, clear commit message (squashed).
  3. …more to come

Conclusion

I think it’s good practice to take stock of your workflows every once in a while to reassess if it’s still a fit. It was clear to me that Mealie’s workflow was overly complicated and causing problems for other contributors and reducing my desire to work on the project. I’m excited about bringing a little more simplicity to the project.

In the next article in this series, I’ll be taking a look at how I can improve the CI/CD pipeline and how the changes in the git workflow impact those changes.