Pushing and branching best practices

Overview

In the previous chapter we covered Git for hardware commit best practices. To review, changes to the files are captured in commits to your local filesystem. Commits should collect small, purposeful, and related changes to the files.

When you’re ready to apply these changes, you push the committed files to a remote repository. The repo might be your own filesystem, a server sitting in a closet, a hosted git solution like GitHub, or a platform specifically designed for hardware like AllSpice.io.

Push to the correct branch

As stressed in the previous chapter, always push your commits to the correct branch. When you clone your repo locally, git should automagically download the project files that associate these files to that repo. The remote server contains access permissions for pushing your commits to the repo.

Part of always committing to the correct branch means restricting people who don’t know how to correctly commit to the correct branch. Every user should be trained on git and given some practice projects to work with before being given write access. It’s easier to prevent a mistake, than to correct it. Training should include pair check-ins and pushes for users who are new to git.

Once you have identified the correct branch, push your files to the branch. The commits aren’t part of the final design yet. The branch is a collection of commits that have been pushed to the remote repo. The commits get merged into your main or release branch via a Pull Request (PR). Because AllSpice is hardware focused, we refer to PRs as Design Reviews (DR). After releasing the Design Review and merging the files from the development branch into the main branch, the Design Review is closed.

In software development, this is usually when the development branch gets deleted and a new branch gets created for the new work. Because of the nature of ECAD files, they do not merge easily. If you change one location in a schematic in one branch and then change another location of the schematic in another commit, you cannot easily merge the files.

If you keep your development branch, any new commits to the development branch requires a new Design Review to merge the pushed changes. Commits pushed to a branch accumulate and then are merged when a Design Review is completed.

2-Branch Strategy: Main and Develop

Because hardware development differs so much from software development, we recommend a branching strategy specifically designed for working with ECAD files. It’s not only simpler, it will often be more productive than the traditional software approach.

Develop in the develop branch and release to the main branch. Each repo contains two branches, one main and one development (dev) branch. The main branch is the default branch and contains all the “correct files” and the development branch includes the work-in-progress changes. When the engineers are ready for their work to be released, you create a pull request or design review from the dev branch to the main branch. When everyone is finished reviewing the design review, one of the users merges the collection of commits and makes copies of them on the main branch. The source files are effectively “released” once they are in main.

Name your branches to match your process. We encourage your team to rename the two branches to something familiar or related to your current process. Prototype→Release, WIP→Final, and Development→Production are all excellent labels for the pair of branches.

This strategy has the advantage of being extremely simple, making onboarding easier and remembering how it works as simple as counting to two.

Add branches when it gets complicated. This approach is not without its drawbacks. If you keep only one development branch, all the pushed commits will be included in the next design review. You will have to do some fancy command line work or use a git client to remove commits or cherry pick some of them to a new branch. The single development branch is more susceptible to errors over time. There are many command line tools that can destroy or mutate your branches beyond recognition. Although all the changes that are merged to the main repo will be saved, you may wind up finding your development branch hopelessly corrupted. You also miss out on the advantage of segmenting the work by user or functional change.

Even with all these potential issues, we still recommend a dec→main branch pair for new users.