Feature Branch Workflow the Promet Way

When you’re wrangling a slightly larger team of developers as we do here at Promet Source, the importance of strict naming conventions becomes apparent pretty quickly. Take the commonly referenced Git workflow from Victor Driessen, for example.

Naming conventions can also integrate nicely with many SaaS products in the marketplace. Project management tools or version control systems with intelligent APIs that automatically cross link open issues or tasks in the project management system with feature branches and/or pull requests in the version control system based on the convention allow for very easy linking to specific issues or tickets. The melding of these two software platforms is great for providing context to a given issue or ticket.

By following naming conventions, a peer reviewer can glean information from the name of the pull request and understand what the related code changes should be addressed. “If you enforce a naming convention like we do at Promet,” says Lisa Ridley, a Solutions Architect on Promet’s Support team, “where you include the client code and issue number in your pull request name, it becomes effortless to pull up the associated task or issue and read what is supposed to be addressed by the code change.”

Not only does a uniform naming convention assist your team in a contextual understanding of code changes, it also prevents confusion. Atlassian’s own Git tutorial on Feature Branch workflow makes mention of the fact that, “Git makes no technical distinction between the master branch and feature branches, so developers can edit, stage, and commit changes to a feature branch just as they did in the Centralized Workflow.”

Make the distinction be apparent to your team with standardized notation. This is an important first step.

Branch Naming the Promet Way

Start by naming your branch. There should be different names for the development and production branches to avoid confusion. From there you should call out what the branch is going to accomplish and identify this with some commonly applied labels, or preface text. 

The most common labels we use for branches are feature, release, and hotfix. It’s a relatively small pool but we find these three provide enough flexibility and descriptive power to explain the feature should another developer jump in at some point.

Any branch that includes a new feature for the future release is a “feature” and we like to include its issue/ticket number plus a brief description. 

Feature Branches:

feature-<issue-key>-<the-description>

There are also branches for release or staging. We identify these with “release” and include a version number for reference.

Release / Staging Branches:

release-v<version-number>

And last but not least, for most bug fixes, quick security updates and production fixes, we use the “hotfix” preface plus version number, issue/ticket number, and description.

Hotfix Branches:

hotfix-v<version-number>-<issue-key>-<the-description>

By using some variation and combination of these three naming conventions we allow for more clarity and visibility into projects that rely on continuous deployment workflow.

Conventional Wisdom

Johnnie Fox, Promet Source CTO, has become an understandably vocal proponent of naming conventions.

“When you’re moving from one project with one convention to another that’s totally different, that’s a bit of friction as a developer that you have to figure out…how things work," says Fox. So, after making pull requests to have someone review your work, you can save time and avoid confusion by following consistent naming conventions.

Andy Kucharski, Promet Source founder, chimes in with an anecdote from his early days:

“When I was sitting down to my very first job as a developer, my manager came over to talk to me and the first thing he told me about was not developing or programming, how to get it done…it wasn’t any of that. It was how to name the files."

Naming conventions aren’t just crucial to the individual who’s performing code review or committing the branch to a Git repository, they’re also a linchpin of success for an entire organization from the top brass down to the most recent hire.

Share Your Thoughts

Does your team use a different naming standard or workflow? We'd like to hear if you have any ideas or suggestions. Stay in touch by subscribing to Promet's newsletter!