Branch model for the BMI repository

[mdpiper]

There are two main branches--develop and stable--in the BMI repository. Here are their roles.

• develop: Development on the BMI is done here. For example, send a PR to this branch if you're proposing a new BMI function. The next BMI release will come from this branch.
• stable: The BMI definition hasn't changed in this branch since the latest release (v2.0). This is the branch we use to build the documentation. Send PRs to this branch with v2.0-compatible bugfixes and improvements to the documentation.

This is close to the git-flow model, with the master branch renamed to stable.

What I'm doing that feels a little fishy is that after changes (e.g., documentation improvements) are merged into stable, I merge stable into develop. This way develop always includes stable. This isn't quite a part the git-flow model, where changes are made on develop then merged back into master after a release. I'm open to suggestions for improvement.

[alee]

This can make for a messy history with merges from stable into develop and back again into stable. I personally prefer having merges one way from feature branches into stable. Instead of having a long-lived development branch, create a new feature branch for the next version of BMI, e.g., v2.0-dev or v2.1-dev, etc. Feature branches always get merged into stable, and there's really no need to merge stable into a feature branch but in case changes in your feature branch depend on an up-to-date version of stable you could also rebase the feature branch and notify collaborators on that branch to update their local repositories

[mdpiper]

I see what you mean--the commit history of develop is cluttered with "Merge branch 'stable' into develop" commits.

[mdpiper]

Experimenting with git cherry-pick on a suggestion from @mwtoews.

[mdpiper]

Here's my next thought on a model for branches.

1. Have two branches, develop and stable, with develop as the main branch
2. Base feature branches and PRs on develop
3. If needed, cherry pick commits into stable

Cherry-picking makes a new commit in stable. This means we won't be able to merge either branch into the other because there will be duplicate commits. (Merging isn't precluded, it's just that branch history will be polluted with the duplicate commits.)

Users don't have to worry about stable; it's just a branch for maintaining the docs.

This process should address the problem of being able to apply changes in a feature branch to both persistent branches.

[mdpiper]

I did a cherry-pick in 8af41c5 from stable to develop. I think it worked alright!

[hellkite500]

You might want to consider using a linear history strategy and only squash or rebase PR' into branches. The github docs describe how to configure github to enforce this startegy. This would cut out any "Merge" commits across the branches, and works much like a cherry-pick workflow, but for the entire branch up to some shared commit.