From 27ca9a8b37704f35ce1a4a6acc918969b130598b Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Tue, 9 Jul 2024 12:00:55 +0200 Subject: [PATCH 01/15] build: use bump-my-version bump2version is no longer maintained --- .bumpversion.cfg | 17 ----------------- pyproject.toml | 5 ++--- 2 files changed, 2 insertions(+), 20 deletions(-) delete mode 100644 .bumpversion.cfg diff --git a/.bumpversion.cfg b/.bumpversion.cfg deleted file mode 100644 index 51e0082c..00000000 --- a/.bumpversion.cfg +++ /dev/null @@ -1,17 +0,0 @@ -[bumpversion] -current_version = 3.0.5 - -[comment] -comment = The contents of this file cannot be merged with that of setup.cfg until https://github.com/c4urself/bump2version/issues/185 is resolved - -[bumpversion:file:deeprank2/__init__.py] -search = __version__ = "{current_version}" -replace = __version__ = "{new_version}" - -[bumpversion:file:pyproject.toml] -search = version = "{current_version}" -replace = version = "{new_version}" - -[bumpversion:file:CITATION.cff] -search = version: "{current_version}" -replace = version: "{new_version}" diff --git a/pyproject.toml b/pyproject.toml index 881c670f..df3c3b43 100644 --- a/pyproject.toml +++ b/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"] From 7b37933b1321c0f4ea56139d75fb5edf1b8206dc Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Tue, 9 Jul 2024 12:01:17 +0200 Subject: [PATCH 02/15] docs: update releasing instructions --- README.dev.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/README.dev.md b/README.dev.md index d15731b3..59d1ad1d 100644 --- a/README.dev.md +++ b/README.dev.md @@ -79,10 +79,68 @@ 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: + +0. **IMP0RTANT:** Create a PR for the release branch (usually `dev`) and make sure that all checks pass! + - if everything goes well, this PR will automatically be closed after the draft release is created. +1. 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. +2. 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). +3. 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. + - If "draft_release" is succesfull but "tidy_workspace" fails, then there are likely merge conflicts with `dev` that are not conflicts with `main`. In the latter case, the draft release is created and it is up to the user to decide whether to proceed with finalizing the release or first resolving the conflicts with `dev` (this should never happen if the release branch was `dev`, as the only change will be the version bump). + - If both jobs succeed, then the draft release is created and the changes are merged into `dev` without any problems and the associated PR is closed. Also, if the release branch is different from `dev`, then that branch will be deleted from the remote repository. +4. Navigate to the [Releases](https://github.com/DeepRank/deeprank2/releases) tab and click on the newest draft + release that was just generated. +5. Click on the edit (pencil) icon on the right side of the draft release. +6. Check/adapt the release notes and make sure that everything is as expected. +7. Check that "Set as the latest release is checked". +8. 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: + +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` and merge the changes into this branch. + - Ensure that the `release` branch is ready to be merged back into `main` (e.g., removing the unnecessary files, fix minor bugs if necessary). + - Also see our [branching strategy](#branching-strategy) above. +2. Ensure 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 ` + 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` 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 From 3fc8fd40d0039db8ef0878b207a178511a514f92 Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Tue, 9 Jul 2024 12:01:46 +0200 Subject: [PATCH 03/15] ci: create workflow for automated github release --- .github/workflows/release_github.yml | 118 ++++++++++++++++++ .../{release.yml => release_pypi.yml} | 0 2 files changed, 118 insertions(+) create mode 100644 .github/workflows/release_github.yml rename .github/workflows/{release.yml => release_pypi.yml} (100%) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml new file mode 100644 index 00000000..334fe998 --- /dev/null +++ b/.github/workflows/release_github.yml @@ -0,0 +1,118 @@ +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} + + steps: + - name: Fail if main branch was selected + if: ${{ github.ref_name }} == 'main' + run: | + echo "Cannot release from main branch, please select valid release branch." + exit 1 + + - name: Checkout repository + uses: actions/checkout@v4 + with: + token: ${{ secrets.GH_RELEASE }} + + - name: Configure git + run: | + git config user.email "actions@github.com" + git config user.name "GitHub Actions" + git pull + + - name: Merge changes into main + run: | + git switch main + git merge ${{ github.ref_name }} --no-ff --no-commit + git merge --continue + + - 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: ${{ secrets.GH_RELEASE }} + + - name: Configure git + run: | + git config user.email "actions@github.com" + 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: | + if [[ ${{ github.ref_name }} != "main" && ${{ github.ref_name }} != "dev" ]]; then + echo "-- deleting branch '${{ github.ref_name }}'" + git push origin -d ${{ github.ref_name }} + else + echo "-- branch '${{ github.ref_name }}' will not be deleted from remote" + fi diff --git a/.github/workflows/release.yml b/.github/workflows/release_pypi.yml similarity index 100% rename from .github/workflows/release.yml rename to .github/workflows/release_pypi.yml From bc88f31204b1f39fc31102f5a30ddb8d6120fde4 Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Tue, 9 Jul 2024 17:10:59 +0200 Subject: [PATCH 04/15] ci: add comment about GitHub token --- .github/workflows/release_github.yml | 2 ++ README.dev.md | 1 + 2 files changed, 3 insertions(+) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml index 334fe998..583e4d86 100644 --- a/.github/workflows/release_github.yml +++ b/.github/workflows/release_github.yml @@ -33,6 +33,7 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: + # token with admin priviliges to override brach protection on main and dev token: ${{ secrets.GH_RELEASE }} - name: Configure git @@ -81,6 +82,7 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: + # token with admin priviliges to override brach protection on main and dev token: ${{ secrets.GH_RELEASE }} - name: Configure git diff --git a/README.dev.md b/README.dev.md index 59d1ad1d..ea1a6bc1 100644 --- a/README.dev.md +++ b/README.dev.md @@ -107,6 +107,7 @@ During the development cycle, three main supporting branches are used: #### 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 From 2dbb4158735682dd81fb059ef7738d551b11ffba Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Tue, 9 Jul 2024 17:20:04 +0200 Subject: [PATCH 05/15] docs: improve release instructions --- README.dev.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.dev.md b/README.dev.md index ea1a6bc1..bcde45f3 100644 --- a/README.dev.md +++ b/README.dev.md @@ -81,7 +81,7 @@ During the development cycle, three main supporting branches are used: ### Automated release workflow: -0. **IMP0RTANT:** Create a PR for the release branch (usually `dev`) and make sure that all checks pass! +0. **IMP0RTANT:** Create a PR pointing to `main` for the release branch (usually `dev`) and make sure that there are no conflicts and that all checks pass! - if everything goes well, this PR will automatically be closed after the draft release is created. 1. 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. @@ -94,9 +94,9 @@ During the development cycle, three main supporting branches are used: directly, you must [create the release manually](#manually-create-a-release). 3. 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. - - If "draft_release" is succesfull but "tidy_workspace" fails, then there are likely merge conflicts with `dev` that are not conflicts with `main`. In the latter case, the draft release is created and it is up to the user to decide whether to proceed with finalizing the release or first resolving the conflicts with `dev` (this should never happen if the release branch was `dev`, as the only change will be the version bump). - - If both jobs succeed, then the draft release is created and the changes are merged into `dev` without any problems and the associated PR is closed. Also, if the release branch is different from `dev`, then that branch will be deleted from the remote repository. + - 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. 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 (note that this should never happen if the release branch was `dev`, as the only change will be the version bump). + - 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, if the release branch is different from `dev`, then that branch will be deleted from the remote repository. 4. Navigate to the [Releases](https://github.com/DeepRank/deeprank2/releases) tab and click on the newest draft release that was just generated. 5. Click on the edit (pencil) icon on the right side of the draft release. @@ -123,7 +123,7 @@ NOTE: the current token (associated to @DaniBodor) allowing to bypass branch pro 0. Make sure you have all required developers tools installed `pip install -e .'[test]'`. 1. Create a `release` branch from `main` and merge the changes into this branch. - Ensure that the `release` branch is ready to be merged back into `main` (e.g., removing the unnecessary files, fix minor bugs if necessary). - - Also see our [branching strategy](#branching-strategy) above. + - Normally speaking, `release` should contain the changes from `dev` (see our [development workflow](#branching-workflow)), although in some cases a hotfix may be implemented from a different branch. 2. Ensure 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 ` From 61b0ab09ecae101d2757958e60aad889417a5d7c Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Fri, 12 Jul 2024 17:52:23 +0200 Subject: [PATCH 06/15] explicitly install ruff version in linting workflow --- .github/workflows/linting.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 4dd13612..8cdcd3c7 100644 --- a/.github/workflows/linting.yml +++ b/.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 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)) From c656ddf5a20d11b0a1ce9ebdd4c8d0b636237875 Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Wed, 17 Jul 2024 13:46:19 +0200 Subject: [PATCH 07/15] ci: fix action --- .github/workflows/release_github.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml index 583e4d86..5e8ec4c3 100644 --- a/.github/workflows/release_github.yml +++ b/.github/workflows/release_github.yml @@ -25,7 +25,7 @@ jobs: steps: - name: Fail if main branch was selected - if: ${{ github.ref_name }} == 'main' + if: ${{ github.ref_name == 'main' }} run: | echo "Cannot release from main branch, please select valid release branch." exit 1 @@ -35,6 +35,8 @@ jobs: 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: | @@ -45,8 +47,8 @@ jobs: - name: Merge changes into main run: | git switch main - git merge ${{ github.ref_name }} --no-ff --no-commit - git merge --continue + git merge origin/${{ github.ref_name }} --no-ff --no-commit + git commit --no-edit - name: Bump version id: bump @@ -84,6 +86,7 @@ jobs: with: # token with admin priviliges to override brach protection on main and dev token: ${{ secrets.GH_RELEASE }} + fetch-depth: 0 - name: Configure git run: | From 9a293188b965f1575442447f6aec7cecbb9ec4e8 Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Mon, 5 Aug 2024 15:40:52 +0200 Subject: [PATCH 08/15] ci: fix linting action --- .github/workflows/linting.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 8cdcd3c7..b870e6e4 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -57,6 +57,6 @@ jobs: python3 --version - name: Check linting and formatting using ruff run: | - python3 -m pip install pip install ruff==0.5.1 + 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)) From f1d829c810b42b638ed75e0e504e46c51267c1e4 Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Fri, 6 Sep 2024 10:01:22 +0200 Subject: [PATCH 09/15] ci: move bumpversion settings to separate toml --- .bumpversion.toml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .bumpversion.toml diff --git a/.bumpversion.toml b/.bumpversion.toml new file mode 100644 index 00000000..b527b8dd --- /dev/null +++ b/.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}"' From ddbd99b1e896fed5ff7088e6fde70cf022ce4a78 Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Fri, 6 Sep 2024 11:13:17 +0200 Subject: [PATCH 10/15] docs: update instructions for manual release --- README.dev.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.dev.md b/README.dev.md index bcde45f3..ef0ef550 100644 --- a/README.dev.md +++ b/README.dev.md @@ -121,11 +121,8 @@ NOTE: the current token (associated to @DaniBodor) allowing to bypass branch pro ### 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` and merge the changes into this branch. - - Ensure that the `release` branch is ready to be merged back into `main` (e.g., removing the unnecessary files, fix minor bugs if necessary). - - Normally speaking, `release` should contain the changes from `dev` (see our [development workflow](#branching-workflow)), although in some cases a hotfix may be implemented from a different branch. -2. Ensure all tests pass `pytest -v` and that linting (`ruff check`) and formatting (`ruff format --check`) conventions - are adhered to. +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 ` where level must be one of the following ([following semantic versioning conventions](https://semver.org/)): - `major`: when API-incompatible changes have been made From c3e884976aa11dd5317588610241ddd1fe5a95cf Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Fri, 6 Sep 2024 11:22:10 +0200 Subject: [PATCH 11/15] ci: do not allow releases from dev branch --- .github/workflows/release_github.yml | 6 +++--- README.dev.md | 22 +++++++++++----------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml index 5e8ec4c3..f95965b1 100644 --- a/.github/workflows/release_github.yml +++ b/.github/workflows/release_github.yml @@ -24,10 +24,10 @@ jobs: shell: bash -l {0} steps: - - name: Fail if main branch was selected - if: ${{ github.ref_name == 'main' }} + - name: Ensure that permitted release branch was selected + if: ${{ github.ref_name == 'main' }} || ${{ github.ref_name == 'dev' }} run: | - echo "Cannot release from main branch, please select valid release branch." + echo "Releasing from main or dev branch is not permitted, please select a valid release branch." exit 1 - name: Checkout repository diff --git a/README.dev.md b/README.dev.md index ef0ef550..4d703fbf 100644 --- a/README.dev.md +++ b/README.dev.md @@ -81,28 +81,28 @@ During the development cycle, three main supporting branches are used: ### Automated release workflow: -0. **IMP0RTANT:** Create a PR pointing to `main` for the release branch (usually `dev`) and make sure that there are no conflicts and that all checks pass! +1. **IMP0RTANT:** Create a PR pointing to `main` for the release branch and make sure that there are no conflicts and that all checks pass. - if everything goes well, this PR will automatically be closed after the draft release is created. -1. Navigate to [Draft Github Release](https://github.com/DeepRank/deeprank2/actions/workflows/release_github.yml) +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. -2. On the right hand side, you can select the level increase ("patch", "minor", or "major") and which branch to release from. +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). -3. Visit [Actions](https://github.com/DeepRank/deeprank2/actions) tab to check whether everything went as expected. +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. If this action is succesfull, then the release branch (including a version bump) have been merged into the remote `main` branch. + - 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 (note that this should never happen if the release branch was `dev`, as the only change will be the version bump). - - 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, if the release branch is different from `dev`, then that branch will be deleted from the remote repository. -4. Navigate to the [Releases](https://github.com/DeepRank/deeprank2/releases) tab and click on the newest draft + - 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. -5. Click on the edit (pencil) icon on the right side of the draft release. -6. Check/adapt the release notes and make sure that everything is as expected. -7. Check that "Set as the latest release is checked". -8. Click green "Publish Release" button to convert the draft to a published release on GitHub. +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: From 604650ba1a07580575da54d396f2e3313caed9f0 Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Fri, 6 Sep 2024 11:41:13 +0200 Subject: [PATCH 12/15] ci: ensure that job fails if a step fails --- .github/workflows/release_github.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml index f95965b1..c8664ee8 100644 --- a/.github/workflows/release_github.yml +++ b/.github/workflows/release_github.yml @@ -22,6 +22,8 @@ jobs: defaults: run: shell: bash -l {0} + strategy: + fail-fast: true steps: - name: Ensure that permitted release branch was selected From f9e536306d3063e4a88a35e2d4fd97e9f80813f9 Mon Sep 17 00:00:00 2001 From: Dani Bodor Date: Fri, 6 Sep 2024 13:43:44 +0200 Subject: [PATCH 13/15] docs: Update README.dev.md Co-authored-by: Giulia Crocioni <55382553+gcroci2@users.noreply.github.com> --- README.dev.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.dev.md b/README.dev.md index 4d703fbf..4d3b19f5 100644 --- a/README.dev.md +++ b/README.dev.md @@ -81,7 +81,7 @@ During the development cycle, three main supporting branches are used: ### Automated release workflow: -1. **IMP0RTANT:** Create a PR pointing to `main` for the release branch and make sure that there are no conflicts and that all checks pass. +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. @@ -95,7 +95,7 @@ During the development cycle, three main supporting branches are used: 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 (note that this should never happen if the release branch was `dev`, as the only change will be the version bump). + - 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. From f8a7fbc7e6f613d720fae08ea7c7c4ca37e80988 Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Fri, 6 Sep 2024 16:01:35 +0200 Subject: [PATCH 14/15] ci: error message if token expired --- .github/workflows/release_github.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml index c8664ee8..d5a8894a 100644 --- a/.github/workflows/release_github.yml +++ b/.github/workflows/release_github.yml @@ -32,6 +32,18 @@ jobs: echo "Releasing from main or dev branch is not permitted, please select a valid 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: From 3472459838df681802b7c7733c1343f680ad741a Mon Sep 17 00:00:00 2001 From: DaniBodor Date: Fri, 6 Sep 2024 19:00:05 +0200 Subject: [PATCH 15/15] ci: fix erroneous branch checking --- .github/workflows/release_github.yml | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/.github/workflows/release_github.yml b/.github/workflows/release_github.yml index d5a8894a..001dfc4f 100644 --- a/.github/workflows/release_github.yml +++ b/.github/workflows/release_github.yml @@ -26,10 +26,16 @@ jobs: 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' }} + if: ${{ github.ref_name == 'main' || github.ref_name == 'dev' }} run: | - echo "Releasing from main or dev branch is not permitted, please select a valid release branch." + 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 @@ -129,9 +135,5 @@ jobs: - name: Delete release branch other than main or dev run: | - if [[ ${{ github.ref_name }} != "main" && ${{ github.ref_name }} != "dev" ]]; then - echo "-- deleting branch '${{ github.ref_name }}'" - git push origin -d ${{ github.ref_name }} - else - echo "-- branch '${{ github.ref_name }}' will not be deleted from remote" - fi + echo "-- deleting branch '${{ github.ref_name }}'" + git push origin -d ${{ github.ref_name }}