Tidy up branches

[David Dickinson]

We have a large number of branches. Many of these are likely to be obsolete or have been merged in etc. It would be good to identify which branches are active, should be archived and should be deleted.

[Stephen Biggs-Fox]

I would say that along with this we need some defined naming conventions for new branches to keep future branches tidy. Maybe we can discuss that here. How about:

bugfix/iss-6 bugfix/iss-7 feat/ball-stab-theta0 feat/nonlinear-optimisation

So to generalise:

• branches are grouped as bug-fixes or new features via the prefix 'bugfix' or 'feat' respectively (one can then filter branches on these keywords to make searching easier)
• the group prefix is separated from the rest of the branch name via a forward slash '/'
• bugfix branches are named after their issue number in the format iss-<#> where <#> is replaced by the number
• feat branches have a short descriptive name of, say, 5 words max
• all letters are lower case
• words are separated by hyphens '-'

How does that sound? If agreed, maybe the description above could go into a CONTRIBUTING document

[David Dickinson]

I think we can have a suggested naming convention (personally I'd rather use _ than /) but I don't think we should be restrictive and absolutely force people to follow this convention. Branches should have a relatively short lifetime going forwards (and can have an associated issue/PR to include on going discussion).

[Stephen Biggs-Fox]

Slash is better than underscore because, when using slash, git will create the groups as separate folders in the .git/refs/heads/ directory of the remote repository, thus keeping the repository tidy. Plus, it's more in keeping with the output of git branch -a. However, I do agree than non-strict enforcement of this convention is a good idea since branches should be short-lived and long-lived branches can easily be renamed if necessary.

[David Dickinson]

I'd suggest that we use issue rather than iss for the sake of two characters (might help non-native speakers). I'd also suggest we need something descriptive as apart of the name if possible (e.g. if the developer is offline they won't be able to see what issue-9 refers to).

[Peter Hill]

Personally, I would be happy with just "prefer lowercase and to separate words with dashes", but otherwise I don't think it's that important.

I will say that abbreviations by two or three letters should be avoided almost everywhere in the codebase though.

[Stephen Biggs-Fox]

Yes, good points from both of you. Plus, if we use 'addresses issue #x' in commit messages then we don't even need the issue number in the branch. We could just have 'bugfix/eigval-typo' etc. If we did something like that, it is still obvious which branch the commits that fix the bug are on because the fixer makes a pull request for that branch.