diff --git a/CHANGELOG.md b/CHANGELOG.md index 70ae707..938633c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ ## HowTos development version +- New guide: How to release new versions of pipelines & tools. (#72, @kelly-sovacool) - Fix minor typos. (#68, @kelly-sovacool) ## HowTos 1.1.0 diff --git a/docs/maintenance/draft-release-page.png b/docs/maintenance/draft-release-page.png new file mode 100644 index 0000000..6e413da Binary files /dev/null and b/docs/maintenance/draft-release-page.png differ diff --git a/docs/maintenance/draft-release-publish.png b/docs/maintenance/draft-release-publish.png new file mode 100644 index 0000000..d91ec7b Binary files /dev/null and b/docs/maintenance/draft-release-publish.png differ diff --git a/docs/maintenance/draft-release-workflow.png b/docs/maintenance/draft-release-workflow.png new file mode 100644 index 0000000..0056b4d Binary files /dev/null and b/docs/maintenance/draft-release-workflow.png differ diff --git a/docs/maintenance/post-release-complete.png b/docs/maintenance/post-release-complete.png new file mode 100644 index 0000000..54c2854 Binary files /dev/null and b/docs/maintenance/post-release-complete.png differ diff --git a/docs/maintenance/post-release-pr.png b/docs/maintenance/post-release-pr.png new file mode 100644 index 0000000..1933790 Binary files /dev/null and b/docs/maintenance/post-release-pr.png differ diff --git a/docs/maintenance/pr-approved.png b/docs/maintenance/pr-approved.png new file mode 100644 index 0000000..d4ca714 Binary files /dev/null and b/docs/maintenance/pr-approved.png differ diff --git a/docs/maintenance/pr-confirm-merge.png b/docs/maintenance/pr-confirm-merge.png new file mode 100644 index 0000000..376cedb Binary files /dev/null and b/docs/maintenance/pr-confirm-merge.png differ diff --git a/docs/maintenance/pr-files-changed.png b/docs/maintenance/pr-files-changed.png new file mode 100644 index 0000000..e73a703 Binary files /dev/null and b/docs/maintenance/pr-files-changed.png differ diff --git a/docs/maintenance/pull-requests.png b/docs/maintenance/pull-requests.png new file mode 100644 index 0000000..096c1a8 Binary files /dev/null and b/docs/maintenance/pull-requests.png differ diff --git a/docs/maintenance/release.qmd b/docs/maintenance/release.qmd new file mode 100644 index 0000000..5a5f902 --- /dev/null +++ b/docs/maintenance/release.qmd @@ -0,0 +1,127 @@ +--- +title: How to Release New Versions +author: "[Kelly Sovacool](https://github.com/kelly-sovacool)" +--- + +How to release new versions of our pipelines and tools using our semi-automated workflow. + +## Check the repo contents + +Ensure it contains the following files: + +- [`CHANGELOG.md`](https://github.com/CCBR/CHAMPAGNE/blob/main/CHANGELOG.md) or [`NEWS.md`](https://github.com/CCBR/MOSuite/blob/main/NEWS.md) + - The first header should be `## development version`. + - Under the header, keep a bulleted list of user-facing changes & links to the PRs that added them. + - If you don't have any entries under the development header, make sure you're updating the changelog with each PR that contains user-facing changes. +- [`VERSION`](https://github.com/CCBR/CHAMPAGNE/blob/main/VERSION) + - Containing only the semantic version. + - If the version file is in a subdirectory, create a symlink at the repo root. + - If your repo is an R package, you don't need this file because the version is in the [`DESCRIPTION`](https://github.com/CCBR/MOSuite/blob/main/DESCRIPTION) file instead. +- [`.github/workflows/draft-release.yml`](https://github.com/CCBR/actions/blob/main/examples/draft-release.yml) +- [`.github/workflows/post-release.yml`](https://github.com/CCBR/actions/blob/main/examples/post-release.yml) + +## Run the tests on the development branch + +If you haven't already, run the test suite on the development branch. +If your repo is a pipeline, use the test dataset/profile/configuration and +make sure it completes without errors on Biowulf. +If your repo is a Python or R package, +the CI workflows should complete successfully in GitHub Actions. + +Do not cut a release if any of the tests fail or if the pipeline throws errors +during the test run. We only want to release working software! + +## Run the `draft-release` workflow + +![](./draft-release-workflow.png) + +## Cut the release + +Once `draft-release` completes successfully, a new draft release will appear under the releases page + +`https://github.com/CCBR//releases` + +![](./draft-release-page.png) + +Click the pencil icon to edit the release. + +![](./draft-release-publish.png) + +If everything looks good, scroll to the bottom and click "**Publish release**". +This will trigger the `post-release` workflow to run, which will then open a +Pull Request (PR) if it completes successfully. +It should take < 2 minutes. + +![](./post-release-complete.png) + +## Review the Pull Request opened by the `post-release` workflow. + +![](./pull-requests.png) + +![](./post-release-pr.png) + +It will bump the version, changelog, and citation file to reflect the next +development version. + +![](./pr-files-changed.png) + +If everything looks good, approve the PR and merge the changes into main. + +![](./pr-approved.png) + +![](./pr-confirm-merge.png) + +Click "**Confirm merge**". + +## Install the new release on Biowulf. + +:::{.callout-note} +You can skip this step if your pipeline/tool is not yet part of the ccbrpipeliner module. +::: + +Log in to biowulf and start an interactive session. +Load the ccbrpipeliner module: + +```sh +module load ccbrpipeliner +``` + +Perform a dry-run of the installation: + +```sh +ccbr_tools install carlisle v2.7.6 +``` + +The dry-run will print the commands that it would execute for a real run: + +```{.email filename="output"} +MAMBA_ROOT_PREFIX='/data/CCBR_Pipeliner/db/PipeDB/miniforge3/' && mamba activate /data/CCBR_Pipeliner/db/PipeDB/miniforge3/envs/py3.11-8 +git clone --depth 1 --single-branch --branch v2.7.6 https://github.com/CCBR/CARLISLE.git /data/CCBR_Pipeliner/Pipelines/CARLISLE/.v2.7.6 +chmod -R a+rX /data/CCBR_Pipeliner/Pipelines/CARLISLE/.v2.7.6 +chmod -R g+rwX /data/CCBR_Pipeliner/Pipelines/CARLISLE/.v2.7.6 +chown -R :CCBR_Pipeliner /data/CCBR_Pipeliner/Pipelines/CARLISLE/.v2.7.6 +pushd /data/CCBR_Pipeliner/Pipelines/CARLISLE +rm -if v2.7 +ln -s .v2.7.6 v2.7 +chmod -R g+rwX v2.7 +popd +``` + +If everything looks good, install it with `--run`: + +```sh +ccbr_tools install carlisle v2.7.6 --run +``` + +You can verify that the installation worked by reloading the module and checking +the version of the pipeline/tool: + +```sh +module load ccbrpipeliner +carlisle --version +``` + +```{.email filename="output"} +Pipeline Dir: /vf/users/CCBR_Pipeliner/Pipelines/CARLISLE/.v2.7.6 +Version: 2.7.6 +```