10

I am in the middle of a disagreement (cordial, of course) with my lead about proper branch naming. This applies to bug-fix and small feature branches, not long-running feature branches. For long-running feature branches, we agree that human-readable names are better. Here are the two points of view:

Mine:

Naming branches according to their team and ticket number is better. It makes it easier to find them in our ticketing system, and shorter to type. It also makes it easier to look up relevant branches in GIT when looking for historical information about a ticket.

Example:

team-name/12345
team-name/53719

His:

Naming branches according to their feature/functionality. It makes it easier to autocomplete, and is easier to remember than individual numbers.

Example:

team-name/fix-that-sql-bug
team-name/expand-http-parser

One compromise I offered is this:

team-name/12345-fix-that-sql-bug

But he does not like this, as it messes with GIT autocomplete.

If this is primarily opinion-based, please feel free to give me guidance on how this can be a better fit for SO - but I think that the reasons I gave can be amended/added to to give an empirical answer.

  • in my experience, best naming for branches for small bug fixes and small features was often trunk (merge early, merge often => no need to isolate changes without a sufficient justification). This of course doesn't apply to back-porting critical fixes to older versions code running in production, for which isolation is justified more than enough (and for which, in turn, it is only natural to name branches after tickets: after all, you're not doing anything particularly meaningful as a feature, you simply are fixing a concrete critical production bug having concrete ticket at it) – gnat Aug 6 '13 at 18:33
5

In this case it seems like you could both compromise on a naming convention that has both the number and description:

Example:

team-name/(12345)-fix-that-sql-bug

team-name/(53719)-expand-http-parser

There really is no correct answer here, it is subjective depending on your point of view.

But if you both compromise you get the best of both worlds. I try and keep this in mind when we have similar disagreements on my team.

Edit:

To deal with the autocomplete issue you can put the numbered id in brackets, this way when you goes to type in a branch you always type ( to see the branches. From this list you will be able to see the numbered id and the description. Simply key in a couple numbers, tab, and it will

  • I agree, and I added this - I think it is silly to disagree with this compromise. – Codeman Aug 6 '13 at 18:02
  • Does autocomplete only work from the start of the branch name? can you put the ID at the end? I don't use the autocomplete functionality so I am unfamiliar with it. – dmck Aug 6 '13 at 18:04
  • yes, it works from start to finish - if you want to get team-name/12345-my-ticket-fix you have to type team-name/123 TAB, essentially. – Codeman Aug 6 '13 at 18:05
  • @Pheonixblade9 See my edit for a possible solution, putting a ( before the ID should prevent you from having to know the ID when typing the branch name – dmck Aug 6 '13 at 18:18
1

It really doesn't matter as long as there is a consistent system that everyone agrees and understands.

I would say though that going by ticket number would keep things easier to remember for which branch to work on. As they directly tie to the issue number rather than a description. Doing only description does seem to make it more difficult to recall which specific issue it is supposed to be and could become long winded trying to avoid being vague.

team-name/bug-that-has-specific-circumstances-to-occur-and-takes-alot-to-describe

0

Naming something solely to take advantage of autocomplete is stupid.

I agree that a link to the bug tracker is important (more important than a good name as it defines exactly the problem being solved by the branch that a couple of words does not) but at the same time, its a usability failure to expect people to know the difference between bug #7312 and #7213. Also its a failure to expect people to get the numbers perfectly right every time - one day someone will commit to the wrong branch because they misread/mistyped 7312 for 7213. (someone on my team did that today!)

So do both - number the branch and add a very short text description just to act as a check. I would put the number first - autocomplete be damned - as you still have to know the text of the branch anyway (eg "bug-fix-for-server" or "fix-bug-for-server" - you still need to know if it starts with f or b!)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.