Skip to content

Latest commit

 

History

History
236 lines (175 loc) · 9 KB

RELEASE.md

File metadata and controls

236 lines (175 loc) · 9 KB

Fed-BioMed release HOWTO

This procedure makes release of software and documentation (published on https://fedbiomed.org). Both are contained in this repository.

Release principle: follow the gitflow release workflow. Can use git commands (see example below) or git-flow commands

pre-release

  • it is recommended to use a fresh clone of the repository to avoid any side effect

  • checkout to develop branch, sync your local clone with remote

git checkout develop
git pull --prune
  • check that the CI for develop builds correctly (github checks)
  • set the release version tag for the release (or use this tag directly in commands)
export RELEASE_TAG=v4.4.0
  • fork a release/$RELEASE_TAG branch from develop, and checkout the release/$RELEASE_TAG branch
git checkout -b release/$RELEASE_TAG

create release + create version tag

  • in the release/$RELEASE_TAG branch, do the release time updates:
    • CHANGELOG.md
    • fedbiomed/common/constants.py : change __version__
  • add new version news in documentation
  • in the release branch, commit the release time updates
git commit -a
  • push the updated release/$RELEASE_TAG
git push origin release/$RELEASE_TAG

merge release to master

  • in github create a pull request for release/$RELEASE_TAG to master

    • one can auto-assign the PR, and doesn't need a review for this PR

  • after checks successfully complete, please review the checks logs

  • create a version tag for the release

    git tag -a $RELEASE_TAG

  • push the tag to the remote

    git push origin $RELEASE_TAG

  • do the merge

  • if merge conflicts occur, solve them

  • check that the documentation pipeline completes successfully

  • browse a few pages in the new documentation on https://fedbiomed.org to verify it works as expected

  • optionally sync your local clone of master with new version of remote

git checkout master
git pull -p

merge release to develop

  • since the release branch was merged into master, it was deleted on remote. There are two options for restoring the branch:
    • either in github, go to the closed PR (the one opened for master) and click on "Restore branch."
    • or checkout the release/$RELEASE_TAG branch and push it again to re-create on the remote 
      git checkout release/$RELEASE_TAG
git push origin release/$RELEASE_TAG
  • in github create a pull request for release/$RELEASE_TAG to develop
    • one can auto-assign the PR, and doesn't need a review for this PR
  • after checks complete, please review the checks logs
  • do the merge
  • if merge conflicts occur, solve them

cleanup

  • delete the (local) release branch
git checkout develop
git branch -d release/$RELEASE_TAG

Fed-BioMed hotfix HOWTO

A hotfix is a patch that is added as a new version patch without changing the API or adding new features, when it can't wait for the next release to be corrected. To apply a hotfix, follow these steps:

This procedure makes hotfix of software and documentation (published on https://fedbiomed.org). Both are contained in this repository.

Release principle: follow the gitflow hotfix workflow. Can use git commands (see example below) or git-flow commands

pre-hotfix

  • it is recommended to use a fresh clone of the repository to avoid any side effect

  • checkout to master branch (Warning: hotfix are not created from develop !), sync your local clone with remote

    git checkout master
git pull --prune

  • check that the CI for master builds correctly (github checks)

  • choose a name (eg 521-short-description) for the issue and assign it to $HOTFIX_NAME

    export HOTFIX_NAME=521-short-description

  • set the hotfix version tag for the release (or use this tag directly in commands).For example, if the previous version was v4.4.0, it becomes v4.4.1.

    export HOTFIX_TAG=v4.4.1

  • fork a hotfix/$HOTFIX_NAME branch from master, and checkout the hotfix/$HOTFIX_NAME branch

    git checkout -b hotfix/$HOTFIX_NAME

create hotfix + create version tag

  • apply the changes for the hotfix

  • in the hotfix/$HOTFIX_NAME branch, do the hotfix time updates:

    • CHANGELOG.md
    • fedbiomed/common/constants.py : change __version__

  • in the hotfix branch, commit the hotfix time updates

    git commit -a

  • push the updated hotfix/$HOTFIX_NAME

    git push origin hotfix/$HOTFIX_NAME

merge hotfix to master

  • in github create a pull request for hotfix/$HOTFIX_NAME to master

    • one can auto-assign the PR, but a reviewer should approve it before merging (different from a release where the code in the PR was already reviewed !)

  • after checks successfully complete, please review the checks logs

  • create a version tag for the hotfix

    git tag -a $HOTFIX_TAG

  • push the tag to the remote

    git push origin $HOTFIX_TAG

  • do the merge

  • if merge conflicts occur, solve them

  • check that the documentation pipeline completes successfully

  • browse a few pages in the new documentation on https://fedbiomed.org to verify it works as expected

  • optionally sync your local clone of master with new version of remote

    git checkout master
git pull -p

merge hotfix to develop

  • since the hotfix branch was merged into master, it was deleted on remote. There are two options for restoring the branch:

    • either in github, go to the closed PR (the one opened for master) and click on "Restore branch."

    • or checkout the hotfix/$HOTFIX_NAME branch and push it again to re-create on the remote

      git checkout hotfix/$HOTFIX_NAME
git push origin hotfix/$HOTFIX_NAME

  • in github create a pull request for hotfix/$HOTFIX_NAME to develop

    • one can auto-assign the PR, and doesn't need a review for this PR

  • after checks complete, please review the checks logs

  • do the merge

  • if merge conflicts occur, solve them

cleanup

  • delete the (local) release branch 
    git checkout develop
git branch -d hotfix/$HOTFIX_NAME

Publishing news, fixing documentation

The changes in website that do not affect User documentation part are also considered as hotfix. These modifications involve:

  • Adding news or updating their content
  • Adding new items to front page (button, boxes, description, new section)
  • Adding new pages (These are pages NOT related to user documentation such as About Us, Roadmap etc.)
  • Adding new items for footer area
  • Changing contents of static pages About us, Contributors etc.
  • Front-End issues broken layout etc.

However, since these modifications don't contain any changes in the Fed-BioMed source code, it is not considered as code patch. It means after applying the changes new version tag SHOULD NOT BE pushed. The process flow is the same as hotfix except that one doesn't push a new tag.

Also, for publishing a news or a doc fix, a review by a third party is not mandatory.

  • Create a new branch hotfix/$HOTFIX_NAME from the master branch.
  • Apply your web-site related changes (please make sure that you change files only in docs directory).
  • Create a pull request (PR) to merge the hotfix branch into the master branch and wait for all the checks to pass.
  • Merge hotfix branch also into develop branch. You can follow the instructions that are explained in hotfix section