Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
kieranhall opened this issue Oct 5, 2023 · 3 comments
Open
Assignees
Labels
fix:bug Something isn't working

Comments

@kieranhall
Copy link
Member

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.

@kieranhall kieranhall added the fix:bug Something isn't working label Oct 5, 2023
@HDauven
Copy link
Member

HDauven commented Oct 11, 2023

@kieranhall this works fine for me. See:
image

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
Copy link
Member Author

kieranhall commented Oct 12, 2023

@kieranhall this works fine for me. See: image

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
Copy link
Member

HDauven commented Oct 12, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
fix:bug Something isn't working
Projects
None yet
Development

No branches or pull requests

4 participants