Branches restructuring

[wyli]

Is your feature request related to a problem? Please describe.

Currently, the MONAI repo has

• master branch: accepting pull requests, new features and/or bug fixes -- full CI/CD tests, nightly tests.
• releases/* branch: branching off from the master, no direct commits allowed -- releasing/packaging related tests
• contributors' pull request forks: code change proposals -- quick pre-merge tests.

This approach is simple and efficient. But it has the problem that there is no place for the new features that are scheduled beyond the current release (they only live in some of the contributors' forks).

Describe the solution you'd like

As we discussed in the dev meeting, we'd like to follow a more rigorous releasing approach.

• main branch: for production-ready features, milestone releases -- releasing/packaging related tests
• dev branch: for all new features -- full CI/CD, nightly tests
• releasing/* branch: a subset of new features from dev, to be released, could have additional bug fixes for releasing
• forks of the contributors: new feature proposals -- quick pre-merge tests

So, the new workflow would be:
The contributors add new features to dev via pull request.
The maintainers plan and build a releasing/* branch (from dev).
The maintainers merge the production-ready releasing/* to main and tag main for a new milestone.
The users download and use the package built from the new release upon main.

Tasks:

• create a dev branch with proper CI/CD
• double-check the offline backup of the repo
• conclude existing PRs
• create a main branch for milestones
• update contributors guide
• revise the CI/CD workflows
• deprecate the master branch
• deprecate the releases/* they are temporary branches, tagged commits are available at main

cc @ericspod

update:

[vfdev-5]

@wyli interesting suggested approach! Curious to see how it works in practice and if it really helps to solve the above issue without headaches of what to merge etc.

In the first approach: master - releases/*, you also can merge all features to the master and prepare releases as a new branch vX.Y.Z starting from somewhere on the master or previous release branch and cherry-picking from master or reverting existing commits. I'd say the idea is almost the same, but branches names are inverted a bit and there is additional main in the second approach...

[wyli]

Hi @vfdev-5 in case you haven't seen it, the approach is mostly adapted from Gitflow https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

main maintains the history of milestones, dev is the integration of features, releases/* and forks are supporting branches

[vfdev-5]

@wyli thanks for the link! Yes, heard recently about gitflow workflow but haven't seen yet in practice on a project that I worked on.

[ericspod]

Gitflow or some parts of it are used for various projects. I feel the important aspect is that the code in master as seen by users is the most recent release so that whatever they get through pip will have matching source code right in front of them. The master/dev/release separation will help with general organization and clean up the commit history for master so that it's easier for non-core developers to see what's one on with the code over time.

One issue we do need to get right is the separation between development and bug fixing. Once a bug in the release branch is identified the fix code must go into a patch release branch derived from master and not from dev, this prevents development code sneaking into the master. The problem is that fix has to find its way into dev as well.

First thing I feel we need to do is start in the habit immediately of not doing PRs directly to master, conclude the PRs open now, setup dev with the right settings for our CI/CD pipelines, and remove any stale branches that don't need to be kept for any reason.

[wyli]

thanks for the comments @ericspod, while waiting for any further comments, let me set up a dev with proper CI/CD, this should be non-breaking, I've updated the task list

[wyli]

looks like renaming master to dev is more convenient... from this doc https://github.com/github/renaming:

Renaming a branch will:

• Re-target any open pull requests
• Update any draft releases based on the branch
• Move any branch protection rules that explicitly reference the old name
• Update the branch used to build GitHub Pages, if applicable
• Show a notice to repository contributors, maintainers, and admins on the repository homepage with instructions to update local copies of the repository
• Show a notice to contributors who git push to the old branch
• Redirect web requests for the old branch name to the new branch name
• Return a "Moved Permanently" response in API requests for the old branch name

[ericspod]

If we're sure our actions and other operations will move over correctly then I'm fine with that. We'd then create a new master as a branch from what was master.

[wyli]

just tested with a separate repo that the renaming works fine.
I'll roll out the branch changes soon.

[ericspod]

Do we want to cleanup the outstanding PRs first? I think these might not react well to a branch rename.

[wyli]

those will be retargeted, should be ok in our case