Create document in repo for branch and PR naming conventions

[petertgiles]

An anonymous card was on the retro board this week: "Create document in repo for branch and PR naming conventions".

As far as I know there is no definitive convention on the team for this. This issue will require some discussion and consensus building.

Note 1: Brinda started a discussion on this topic on Slack a long time ago: https://talent-cloud.slack.com/archives/C0259G6KXJ6/p1638818249035500

Note 2: The pattern of using a forward slash in the branch name allows folding in gitlens:

Note 3: (TODO: Something about starting with the issue number allows auto complete?)

[esizer]

I like and usually try to following this recommendation since everything makes sense to me, would be curious to see what others think.

https://hackernoon.com/git-branch-naming-convention-7-best-practices-to-follow-1c2l33g2

[petertgiles]

I've started using worktrees lately. Using a slash as a separator in the branch name is inconvenient there since git will take the last component of the path as the new branch name. So a prefix like "feature/" or "bug/" will become part of the path but not the branch name.
https://git-scm.com/docs/git-worktree

[esizer]

Using a slash as a separator in the branch name is inconvenient there

So, would underscore be a better separator, @petertgiles ? i.e

label_555_branch-name

[petertgiles]

I don't have a preference between underscore or hyphen. Just no slashes.

[tristan-orourke]

I prefer just hyphens. Using two types of separator just seems inconvenient.

[esizer]

I am currently using underscores to group/separate different units of information (previously "/" for git tree organization but it was mess with peters workflow).

I find only kebab case fairly difficult to read and the underscore helps separate the information more clearly where a hyphen is a stand in for white space.

[brindasasi]

I was using this before .. but now changed to just hyphens.. life is better now! 😊

[tristan-orourke]

I remember addressing this question once, a long time ago, and as far as I remember the conclusion was that the "label" (feature, bug, bugfix, etc) didn't add any useful information, and was kind of redundant anyway, since most of our branches are feature branches.

My vote is to stick with <issue number>-plus-some-descriptive-title.

[petertgiles]

Seems simple and useful. I like it. 👍

[esizer]

I would prefer to not begin a branch name with numbers, it does not make it very friendly to tab completion 😢

[mnigh]

i am cool with prepending a word to the branch name, as long as it's one of the following (if i am missing another useful identifier, i am open to it, but i can't think of another that doesn't fit into one of these):

• release
• feature
• bug

[vd1992]

starting things with numerals, like sentences, always feels wrong

[tristan-orourke]

Counterpoint, issue numbers are very friendly to tab completion, if you know which issue you're looking for (which is how I normally look for branches) 😝

[mnigh]

how about a convention for PR titles? i like:

<type> - <issue number> - Some Descriptive Title
Debt - 5290 - Removes Deprecated Role and Salary API Fields

what do other @GCTC-NTGC/developers like?

[petertgiles]

I'm not sure I like type and issue number in the title. All that metadata is already in the PR.

[esizer]

I like to have at least the label in the title, it makes it easier to prioritize reviews at a glance instead of having to click through. I use issue number right now but since it appears below the PR title anyway and in the description it is kind of redundant.

[brindasasi]

I'm fine with either. I'm not doing it currently but like the idea of having some convention. PRs will look organized.
Either every one adds the prefix .. or no one adds it 😅

[tristan-orourke]

Okay, I'm going to make a call on these! Here are our new conventions:

Branch names: <issue number>-plus-some-descriptive-title
Release branches are an exception: release/vX.Y.Z
PR Titles: [<type>] And some nice descriptive title