CONTRIBUTING.md gives advice on branch name that is invalid for Git

[kieranhall]

Describe the bug
In the CONTRIBUTING.md file, there is advise to create a branch named something like feature-[issue_nr]. However, if you try to make a branch using that format (or even that exact example), then you get an error: fatal: 'feature-[issue_nr]' is not a valid branch name..

To Reproduce

• Clone any repo
• Checkout a new branch (git checkout -b feature-[issue_nr])

Expected behaviour
The CONTRIBUTING.md file should give valid examples for developers to follow, such that questions over conventions are made irrelevant.

Logs/Screenshot

$ git checkout -b feature-[issue_nr] ⬡ 18.12.0 [±main ✓]
fatal: 'feature-[issue_nr]' is not a valid branch name.

[HDauven]

@kieranhall this works fine for me. See:

Unless you're using the [ and ] literally. Those are not allowed.

Either way, we do not strongly enforce this rule internally. Should we? Or should we only apply this to external contributors?

[kieranhall]

@kieranhall this works fine for me. See:

Unless you're using the [ and ] literally. Those are not allowed.

Either way, we do not strongly enforce this rule internally. Should we? Or should we only apply this to external contributors?

Your example works fine and would be a better example in the guide IMO. In the guide the example is also in code format, which I expect to be something you can directly copy. It's a nitpick point, and probably most developers would already know that brackets are not valid syntax, but I just don't like the use of them in guides for variables. I think it's better to give a concrete example. If you agree, I will make a PR to improve this section of the guide.

WRT enforcing. Yes, I think we should enforce a standard approach to branch naming. Personally, I think branches should be named like noun/issue-number e.g. feature/101. This is because many Git tools treat the / as directory separator, and will enable branches to be collapsed accordingly. This can easily be enforced with a regular expression, and pre-receive hooks for Github Enterprise, and probably by doing something with Actions without us switching to Enterprise. Alternatively we could provide pre-push hooks for developers to download and use in our projects and enforce policies when reviewing pull requests.

[HDauven]

WRT enforcing. Yes, I think we should enforce a standard approach to branch naming. Personally, I think branches should be named like noun/issue-number e.g. feature/101...

I don't have a strong opinion here and am fine with whatever we pick.