jimeh / common-flow Goto Github PK

• Long-term release branches should be though of as the master branch for version in question. Hence force pushes are never allowed.
• Short-Term release branches typically should never be force pushed to. However if the branch hasn't been tagged with a release yet, it is ok to rebase the short-term release branch on top of it's source branch if there's new changes that need to be pulled in. But ONLY when the branch does not yet have a release tag on it.

Firstly thanks for the great summary. This will be useful for many teams, ours included!

Just wondering around the justification for:

To create a new release, you MUST create a "version bump" commit which changes the hard-coded version string of the project. The version bump commit MUST have a git tag created on it and named as the exact version string.

This is a MUST, but as far as I can see it doesn't serve a purpose given the releases are tagged. It may also have consequences such as triggering CI again and polluting history.

The FAQ section can go into a bit more detail about certain situations, including examples of git commands to run, and more.

If you have any questions you'd like answered in the FAQ, please leave a comment on this issue.

Questions

• What does "descriptive name" mean in terms of change branches?
• What if there's a emergency hotfix that needs to be released, but for whatever reason, master has changes that cannot be released right now?

common-flow should accommodate for situations where it is necessary to use main.

I do not want to discuss whether one should use main or master as a branch name.

For short-term branches I don't care much -- seeing them helps you remember to make sure they're closed, but for long-term release branches....

Many GUI tools (specifically including azure git which my employer uses, but also tools like gitkraken, source tree, etc.) show path-like branch names as folders, so if a team uses / instead of - as the separator, then releases are rendered neatly as if in a folder (and are hideable when you're doing normal work and don't care about them).

I noticed you don't favor the feature/ type prefixes for branch names either and I wondered if you're against path-like branch names in general (and if you have a reason), or if you have a reason for avoiding them here (since you specifically left the option open on change branches)...

As an aside: I'm actually updating git workflow policy for an org with more repositories than feature teams. Our teams work across all repositories (in theory), so we're considering recommending developers create branches like teamname/change-description or even teamname/storyid/change-description (where the story id is in our issue tracker) so that other developers can easily tell which teams are currently working on any project, and even look up the big-picture information about it ...

While it is "RECOMMENDED that you commit often locally", I think that the flow should allow for (or indeed encourage) developers to reformat this stream of commits into a comprehensible patch set before opening a pull request. This would add a "git rebase -i" step before creating the pull request, where commits can be squashed and reordered and commit messages touched up.

Also: although I don't see this spelled out, the diagram suggests that issues that come up in review get fixed by adding more commits. I would suggest allowing (and recommending) the original commits to be fixed and re-uploaded for review instead, as this produces a cleaner history and also makes several review passes manageable. This is the natural workflow with some tooling (e.g. Gerrit).

I'm evaluating branching models for my company as we transition to a git workflow, and really like this proposal. However, my reading of it implies that release tags get reused in long term release branches. In particular, this statement in 8.iv:

Long-term release branches for maintenance releases of older versions MUST be created from the relevant release tag. For example if the master branch is on version 2.11.4 and there is a security fix for all 2.9.x releases, the latest of which is "2.9.7". Create a new branch called "release-2.9" off of the "2.9.7" release tag. The security fix release will then end up being version "2.9.8".

Is the 2.9.7 release tag on the master branch? If so, wouldn't the next commit to the master branch be 2.9.8? And, now the first commit to the release-2.9 branch is also 2.9.8? Or, did I misinterpret some of the statements?

(not because it's hard, but because I had to go look it up)

We've just migrated across to git and enterprise GitHub in my workplace. While many of us would like to rebase everything all the time to keep a clean history, we've actually had to implement a BAN on rebasing for any branch which has become part of a GitHub Pull Request. The reason for this is simply that GitHub can't track which comments belonged to which commits if you rebase.

While I personally appreciate the value of rebasing, making it a mandatory part of common-flow makes it impossible for us to adopt this policy without modifications.

There is a sort-of footnote in the git best practices section:

vi. It is RECOMMENDED that all branches be merged using "git merge --no-ff". This makes sure the reference to the original branch is kept in the commits, allows one to revert a merge by reverting a single merge commit, and creates a merge commit to mark the integration of the branch with master.

I think this should be moved/copied to section 4 where you're initially discussing merging pull requests and change branches (just as the --force-with-lease is mentioned when rebasing is mentioned). My suggestion would be to insert 10-vi into 4 as a new v (pushing the current v to vi).

I want to stress this is low priority and for after 1.0 release.

Many points require a decision for a specific strategy inhouse. For example, either have a VERSION file or inject the version dynamically.

Therefore i would propose creating a collection of questions/selections that need to be made before the spec can be used "in the wild".

Even cooler would be if these selections would then generate a version of the spec without SHOULD or RECOMMENDED, but only the specific selections made. That would make it easy to send the spec to colleagues.

Minor comment on Grammar: use "from" instead of "off of".
See the following sections: in 1.0.0-rc.4

• 8 iv
• FAQ Bullet 2