ci: improve release workflow

.bumpversion.toml

@@ -0,0 +1,17 @@
+[tool.bumpversion]
+current_version = "3.0.5"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "CITATION.cff"
+search = 'version: "{current_version}"'
+replace = 'version: "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "deeprank2/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

.github/workflows/linting.yml

@@ -57,6 +57,6 @@ jobs:
           python3 --version
       - name: Check linting and formatting using ruff
         run: |
-          python3 -m pip install ruff
+          python3 -m pip install ruff==0.5.1
           ruff check || (echo "Please ensure you have the latest version of ruff (`ruff -V`) installed locally." && (exit 1))
           ruff format --check || (echo "Please ensure you have the latest version of ruff (`ruff -V`) installed locally." && (exit 1))

.github/workflows/release_github.yml

@@ -0,0 +1,139 @@
+name: Draft GitHub Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_level:
+        description: "Semantic version level increase."
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  draft_release:
+    runs-on: "ubuntu-latest"
+    defaults:
+      run:
+        shell: bash -l {0}
+    strategy:
+      fail-fast: true
+
+    steps:
+      - name: Display selection
+        run: |
+          echo "Branch selected: '${{ github.ref_name }}'"
+          echo "Release level selected: '${{ github.event.inputs.version_level }}'"
+
+      - name: Ensure that permitted release branch was selected
+        if: ${{ github.ref_name == 'main' || github.ref_name == 'dev' }}
+        run: |
+          echo "Branch selected: '${{ github.ref_name }}'"
+          echo "Releasing from main or dev branch is not permitted, please select a different release branch."
+          exit 1
+
+      - name: Check GitHub Token Validity
+        run: |
+          echo "-- Validating GitHub Token"
+          status_code=$(curl -o /dev/null -s -w "%{http_code}" -H "Authorization: token ${{ secrets.GH_RELEASE }}" https://api.github.com/user)
+          if [ "$status_code" -ne 200 ]; then
+            echo "Error: GitHub token is invalid or expired. Please update your token in secrets."
+            echo "Instructions can be found at: https://github.com/DeepRank/deeprank2/blob/main/README.dev.md#updating-the-token"
+            exit 1
+          else
+            echo "GitHub token is valid."
+          fi
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # token with admin priviliges to override brach protection on main and dev
+          token: ${{ secrets.GH_RELEASE }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.email "[email protected]"
+          git config user.name "GitHub Actions"
+          git pull
+
+      - name: Merge changes into main
+        run: |
+          git switch main
+          git merge origin/${{ github.ref_name }} --no-ff --no-commit
+          git commit --no-edit
+
+      - name: Bump version
+        id: bump
+        run: |
+          echo "-- install bump-my-version"
+          python3 -m pip install bump-my-version
+          echo "-- bump the version"
+          bump-my-version bump ${{ github.event.inputs.version_level }} --commit --tag
+          echo "-- push bumped version"
+          echo "RELEASE_TAG=$(git describe --tags --abbrev=0)" >> $GITHUB_OUTPUT
+          git push --tags -f
+          git push
+
+      - name: Create GitHub Release
+        id: create_release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create ${{ steps.bump.outputs.RELEASE_TAG }} \
+              --title="Release ${{ steps.bump.outputs.RELEASE_TAG }}" \
+              --generate-notes \
+              --draft
+
+  tidy_workspace:
+    # only run if action above succeeds
+    needs: draft_release
+    runs-on: "ubuntu-latest"
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # token with admin priviliges to override brach protection on main and dev
+          token: ${{ secrets.GH_RELEASE }}
+          fetch-depth: 0
+
+      - name: Configure git
+        run: |
+          git config user.email "[email protected]"
+          git config user.name "GitHub Actions"
+          git pull
+
+      - name: Close PR
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          echo "-- searching for associated PR"
+          pr_number=$(gh pr list --head ${{ github.ref_name }} --json number --jq '.[0].number')
+          if [ -n "$pr_number" ]; then
+            echo "-- closing PR #$pr_number"
+            gh pr close $pr_number
+          else
+            echo "-- no open pull request found for branch $branch_name"
+          fi
+
+      - name: Merge updates into dev
+        run: |
+          git switch dev
+          git merge origin/main
+          git push
+
+      - name: Delete release branch other than main or dev
+        run: |
+          echo "-- deleting branch '${{ github.ref_name }}'"
+          git push origin -d ${{ github.ref_name }}

README.dev.md

@@ -79,10 +79,66 @@ During the development cycle, three main supporting branches are used:
 
 ## Making a release
 
-1. Branch from `dev` and prepare the branch for the release (e.g., removing the unnecessary dev files, fix minor bugs if necessary).
-2. [Bump the version](https://github.com/DeepRank/deeprank2/blob/dev/README.dev.md#versioning).
-3. Merge the release branch into `main` (and `dev`), and [run the tests](https://github.com/DeepRank/deeprank2/blob/dev/README.dev.md#running-the-tests).
-4. Go to https://github.com/DeepRank/deeprank2/releases and draft a new release; create a new tag for the release, generate release notes automatically and adjust them, and finally publish the release as latest. This will trigger [a GitHub action](https://github.com/DeepRank/deeprank2/actions/workflows/release.yml) that will take care of publishing the package on PyPi.
+### Automated release workflow:
+
+1. **IMP0RTANT:** Create a PR for the release branch, targeting the `main` branch. Ensure there are no conflicts and that all checks pass successfully. Release branches are typically: traditional [release branches](https://nvie.com/posts/a-successful-git-branching-model/#release-branches) (these are created from the `dev` branch), or [hotfix branches](https://nvie.com/posts/a-successful-git-branching-model/#hotfix-branches) (these are created directly from the `main` branch).
+   - if everything goes well, this PR will automatically be closed after the draft release is created.
+2. Navigate to [Draft Github Release](https://github.com/DeepRank/deeprank2/actions/workflows/release_github.yml)
+   on the [Actions](https://github.com/DeepRank/deeprank2/actions) tab.
+3. On the right hand side, you can select the level increase ("patch", "minor", or "major") and which branch to release from.
+   - [Follow semantic versioning conventions](https://semver.org/) to chose the level increase:
+     - `patch`: when backward compatible bug fixes were made
+     - `minor`: when functionality was added in a backward compatible manner
+     - `major`: when API-incompatible changes have been made
+   - Note that you cannot release from `main` (the default shown) using the automated workflow. To release from `main`
+     directly, you must [create the release manually](#manually-create-a-release).
+4. Visit [Actions](https://github.com/DeepRank/deeprank2/actions) tab to check whether everything went as expected.
+   - NOTE: there are two separate jobs in the workflow: "draft_release" and "tidy_workspace". The first creates the draft release on github, while the second merges changes into `dev` and closes the PR.
+     - If "draft_release" fails, then there are likely merge conflicts with `main` that need to be resolved first. No release draft is created and the "tidy_workspace" job does not run. Coversely, if this action is succesfull, then the release branch (including a version bump) have been merged into the remote `main` branch.
+     - If "draft_release" is succesfull but "tidy_workspace" fails, then there are likely merge conflicts with `dev` that are not conflicts with `main`. In this case, the draft release is created (and changes were merged into the remote `main`). Conflicts with `dev` need to be resolved with `dev` by the user.
+     - If both jobs succeed, then the draft release is created and the changes are merged into both remote `main` and `dev` without any problems and the associated PR is closed. Also, the release branch is deleted from the remote repository.
+5. Navigate to the [Releases](https://github.com/DeepRank/deeprank2/releases) tab and click on the newest draft
+   release that was just generated.
+6. Click on the edit (pencil) icon on the right side of the draft release.
+7. Check/adapt the release notes and make sure that everything is as expected.
+8. Check that "Set as the latest release is checked".
+9. Click green "Publish Release" button to convert the draft to a published release on GitHub.
+   - This will automatically trigger [another GitHub workflow](https://github.com/DeepRank/deeprank2/actions/workflows/release.yml) that will take care of publishing the package on PyPi.
+
+#### Updating the token:
+
+In order for the workflow above to be able to bypass the branch protection on `main` and `dev`, a token with admin priviliges for the current repo is required. Below are instructions on how to create such a token.
+NOTE: the current token (associated to @DaniBodor) allowing to bypass branch protection will expire on 9 July 2025. To update the token do the following:
+
+1. [Create a personal access token](https://github.com/settings/tokens/new) from a GitHub user account with admin
+   priviliges for this repo.
+2. Check all the "repo" boxes and the "workflow" box, set an expiration date, and give the token a note.
+3. Click green "Generate token" button on the bottom
+4. Copy the token immediately, as it will not be visible again later.
+5. Navigate to the [secrets settings](https://github.com/DeepRank/deeprank2/settings/secrets/actions).
+6. Edit the `GH_RELEASE` key giving your access token as the new value.
+
+### Manually create a release:
+
+0. Make sure you have all required developers tools installed `pip install -e .'[test]'`.
+1. Create a `release-` branch from `main` (if there has been an hotfix) or `dev` (regular new production release).
+2. Prepare the branch for the release (e.g., removing the unnecessary dev files, fix minor bugs if necessary). Do this by ensuring all tests pass `pytest -v` and that linting (`ruff check`) and formatting (`ruff format --check`) conventions are adhered to.
+3. Bump the version using [bump-my-version](https://github.com/callowayproject/bump-my-version): `bump-my-version bump <level>`
+   where level must be one of the following ([following semantic versioning conventions](https://semver.org/)):
+   - `major`: when API-incompatible changes have been made
+   - `minor`: when functionality was added in a backward compatible manner
+   - `patch`: when backward compatible bug fixes were made
+4. Merge the release branch into `main` and `dev`.
+5. On the [Releases page](https://github.com/DeepRank/deeprank2/releases):
+   1. Click "Draft a new release"
+   2. By convention, use `v<version number>` as both the release title and as a tag for the release.
+   3. Click "Generate release notes" to automatically load release notes from merged PRs since the last release.
+   4. Adjust the notes as required.
+   5. Ensure that "Set as latest release" is checked and that both other boxes are unchecked.
+   6. Hit "Publish release".
+      - This will automatically trigger a [GitHub
+        workflow](https://github.com/DeepRank/deeprank2/actions/workflows/release.yml) that will take care of publishing
+        the package on PyPi.
 
 ## UML
 

pyproject.toml

@@ -57,17 +57,16 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-# development dependency groups
 test = [
     "pytest >= 7.4.0, < 8.0",
-    "bump2version >= 1.0.1, < 2.0",
+    "bump-my-version >= 0.24.2, < 1.0",
     "coverage >= 6.5.0, < 7.0",
     "pycodestyle >= 2.8.0, < 3.0",
     "pytest-cov >= 4.1.0, < 5.0",
     "pytest-runner >= 6.0.0, < 7.0",
     "coveralls >= 3.3.1, < 4.0",
     "ruff == 0.6.3",
-]
+] # development dependency groups
 publishing = ["build", "twine", "wheel"]
 notebooks = ["nbmake"]