retire "master" branch

[orbeckst]

trafficstars

Background

MDAnalysis has existed for a while and so there’s a bit of history built into our development process. One of these pieces of history is that we follow the git-flow development model http://nvie.com/posts/a-successful-git-branching-model/ (see https://github.com/MDAnalysis/mdanalysis/issues/96 ; the post from 2010 also has a 2020 update). In this model, development is carried out on the develop branch and release-ready code is merged into the master branch. Feature branches are branched off of develop.

Experience over the last 10+ years has shown that for MDAnalysis, the develop branch is stable and useable (mainly thanks to broad testing) and that the master branch is little more than a place to hold release tags. We also don’t have the capacity to support multiple releases in parallel (for instance, MDA 1.x is legacy now and we are not updating it anymore). Many other projects have adopted a rolling development model with a single main branch that is continually updated. In this model, releases are either short branches of the main branch or just tags.

Change: Retire master branch

I propose that we adopt the single main-branch model for future MDAnalysis development.

In effect, we will just retire master and continue working on develop as before.

Releases will be branched off of develop. We can keep the name ‘develop’ for this branch.

This change should simplify our release management and syncing the structure of the User Guide (which has versions for current development and published releases).

Discussion

The proposal was discussed on the developer list https://groups.google.com/g/mdnalysis-devel/c/ncocXN3EoaE/m/YfJQwjAIFgAJ and found broad agreement.

@jbarnoud commented:

At some point, it was question to have one branch per major version (1.x, 2.x) for the occasional backport. Is it still the idea?

Yes. (Although we decided not to touch 1.x anymore as the CI for Python 2.7 is too complicated and fragile. The discussion for long term support/backports is also open.)

@tylerjereddy commented

• Sounds good, there are also ethical reasons to distance a project from a branch named "master."
• Creating small release branches off of develop would mirror NumPy/SciPy as well, if you go that route.

[IAlibay]

Do we need to do anything here?

As far as I'm aware all this means is that starting next release (i.e. 2.1.0) I'll just make a tag and/or feature branch and go with that?

I guess the main decision is - are tags good enough or do we want a feature branch for each release?

[jbarnoud]

I would say that just the tag is good enough. We can always create a branch from that commit if needed. What would be the workflow, then? One commit sets the version number and the date in the changelog, that commit gets tagged, next commit sets the dev version number and add the dev version in the changelog?

[IAlibay]

We'll see how it plays out in practice, but yeah I was planning to do something similar-ish.

1. PR to tie off version numbers + changelog
2. Complete feature freeze whilst we test things on TestPypi
3. Merge PR
4. Tag commit, upload to pypi
5. New PR to start next version.

Point 2 is going to be really important, we can't have anything going in whilst we make sure that things work fine on testpypi (it's an important step because we've caught out some real bad stuff via testpypi in the past).

[IAlibay]

After speaking with @lilyminium we'll need to make sure we have a release feature branch so that the userguide has somewhere to point to.

[jbarnoud]

Does the user guide point to a branch or to a commit? Anyway, branching out of the tagged commit shouldn't be an issue.

[IAlibay]

Does the user guide point to a branch or to a commit? Anyway, branching out of the tagged commit shouldn't be an issue.

I'll leave this to discussions with @lilyminium once she's back from leave.

To do (will self-assign as per our last meeting)

• [x] update wiki
• [ ] update userguide

[lilyminium]

User guide points to a branch for now, but it's no work at all to make it point to a tag instead.

[lilyminium]

However, I'd probably branch the user guide for individual releases as it's more living than the codebase or docs.

[orbeckst]

@IAlibay should we move this to 2.2.x or can we close?

[IAlibay]

Just keeping this open for now, got a few documentation things to update still.

[IAlibay]

@lilyminium does anything need to be done re: useguide?

[IAlibay]

Should be all fixed now.