search

NOAA-FIMS / collaborative_workflow

contributors guide to FIMS, managing collaborations
https://noaa-fims.github.io/collaborative_workflow/
4 stars 1 forks source link

relax branch naming convention described in handbook #134

Closed iantaylor-NOAA closed 2 weeks ago

iantaylor-NOAA commented 1 month ago

Our branch naming convention in the handbook (added in Feb 2022) has 4 elements: group word, issue ID, description, and hyphens in between (e.g. feat-issue-3-R-package-skeleton). https://github.com/NOAA-FIMS/collaborative_workflow/blob/9da348b5ea7ffa32cb762c5048ef817268755906/07-contributor-guide.Rmd#L209-L223

However, none of our 12 existing branches https://github.com/NOAA-FIMS/FIMS/branches follow that convention (in most cases, the "description" part is the only one of the 4 elements that we're following and it seems like we're doing just fine keeping track of them.

Rather than adopt the stated convention, I think we should rewrite the handbook to better match what we're already doing.

How about we relax the stated convention to focus on the last 2 pieces, a description and using hyphens instead of underscores? We have a mix of underscores and hyphens, but hyphens seem to be more standard in other packages (e.g. https://github.com/tidyverse/ggplot2/branches/all).

k-doering-NOAA commented 1 month ago

Agree to relax the naming conventions!

I'm going to go a step further and suggest that as long as the branch name describes the work, it is fine, regardless of if hyphens or underscores are used in the name. I don't see the value in enforcing a strong branch convention (but other should feel free to disagree!)

kellijohnson-NOAA commented 1 month ago

I agree with @k-doering-NOAA because we are not actually using the branch names for anything downstream, e.g., writing a change log or sending summary emails. GitHub already has a few built-in conventions that it checks prior to pushing a branch regarding the branch name, such as looking for $, which is not allowed unless it is escaped.

If we want more structure, I propose that we initiate some web-hooks that constrain allowable branch names rather than having guidance in the collaborative workflow that is difficult to remember to follow. For example, if we want to use "-" as a separator, we could disallow "_" in the branch names and users would get an error when pushing to GitHub if their branch name contained disallowed characters. I think this is overkill at the moment though.