GitFlow

[ebuchman]

Git Workflow

How should we co-ordinate changes to our software?

Let's write some requirements and see the pros and cons of different branching/release models.

Requirements

• easy to understand / use
• easy to prepare accurate changelogs
• reasonably readable commit history
  • should be easy to see which set of commits came together in a PR
• high integrity review process
  • minimize rebases and cherry-picks of already reviewed code
• use github permissions / automation for merges and releases
  • all changes in released code should have a corresponding PR
• releases are reviewed/approved
  • dont tag official releases from non-reviewed-and-merged branches
• support "previous", "current", and "next" releases of the software (ie. backports and some semblance of stability on the main branch/es)

Just Use Master

• all PRs are made against master
• release: prepare release branch, merge, tag from master
• master is github protected branch

Pros

• easiest
• commits only merged once (ie. in one PR to master)
• release branch only contains "release preparation" commits

Cons

• doesn't natively support backports
• default branch is unstable

Use Master and a branch for each Release Series

• start with "Just Use Master"
• create release-0.x branch for each minor version x
• fixes are branches off and merged into relevant release-0.x branch
• release:
  • prepare release branch release/0.x.y based on release-0.x
  • PR and merge to release-0.x
  • get fix back to master. could be done multiple ways:
    • branch off master, rebase/cherry-pick fix, PR against master
      • this destroys integrity but is clean
    • PR the original fix branch against master
      • doesnt include changelog/version bump
    • PR the full release branch against master
      • includes changelog/version bump, likely conflicts

Pros

• easy
• most commits only merged once (in one PR to master)
  • tho commits to fix old releases may need to be merged again to get the fix back to master
• can easily make PRs based on the latest release of any minor version series to backport fixes

Cons

• each release-0.x branch requires github protection
• undecided how to get fixes back to master

Use Master and Develop

• all PRs against develop
• master is last release
• release:
  • branch off develop, prepare release branch, PR to master
  • merge release PR to master
  • tag master as the new release
  • PR master back to develop

Pros

• can easily make a PR to the latest release to backport fixes
• features/fixes are merged once (PR to develop)
• merges to master only happen on release
• the latest release has a homepage
  • easier to see the readme on master than on the latest release

Cons

• More difficult
• Can be lots of merging back and forth between master and develop

Use GitWorkFlow

This is the workflow used by git.git itself. It has 4 branches:

• maint: maintenance branch for latest release
• master: beta code
• next: alpha code
• pu: "proposed updates", throw away branch used to ensure compatibility of existing feature branches

Here, pu branch is constantly thrown away and reset. Only topic branches are ever merged directly back to master.

Pros

• very clear separation of concerns
• focus on fleshing out topic branches in full
• apparently more scalable

Cons

• much more difficult
• feature branches are merged multiple times (eg. once to pu to try with other branches, then the feature branch itself would get merged to master once it's found to be ok - never merge pu anywhere)

[alexanderbez]

Im inclined to say that "Use Master and a branch for each Release Series" seems like the more sensible path. I've noticed other well maintained large open source repositories do this as well. Regarding on how to "get fixes back to master", it seems that opening a PR of the original fix branch against master would make sense. We don't get the version/changelog updates here, but how much headache would that cause to do manually?

[rigelrozanski]

support "previous", "current", and "next" releases of the software (ie. backports and some semblance of stability on the main branch/es)

good point!

sounds like Just Use Master option is excluded from this. GitWorkFlow seems pretty confusing - from the provided description, I'm still a bit unclear on the use of pu branch 💩 .

[ValarDragon]

I'm confused on GitWorkFlow as well. I think we want something easy to understand, so new contributors can join.

I personally like master + develop. I wouldn't be opposed to merging CLI/UX changes and hot fixes directly to master though.

[zramsay]

i think a good flow is fairly well established. re-open if conversation needs to be continue