docs: update dev readme for releasing

.github/workflows/release_github.yml

@@ -17,7 +17,7 @@ permissions:
   pull-requests: write
 
 jobs:
-  github_release:
+  draft_release:
     runs-on: "ubuntu-latest"
     defaults:
       run:
@@ -72,7 +72,7 @@ jobs:
 
   tidy_workspace:
     # only run if action above succeeds
-    needs: github_release
+    needs: draft_release
     runs-on: "ubuntu-latest"
     defaults:
       run:

README.dev.md

@@ -81,20 +81,24 @@ During the development cycle, three main supporting branches are used:
 
 ### Automated release workflow:
 
-0. **IMP0RTANT:** Create a PR for the release branch and make sure that all checks pass!
-   - if everything goes well, this PR will automatically be closed.
+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.
-   - if released from a different branch than `develop`, then the workflow will attempt to merge the changes into develop
-     as well. If succesfull, the release branch will be deleted from the remote repository.
-   - [follow semantic versioning conventions](https://semver.org/) to chose the level increase:
+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 (which was just automatically generated)
+   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".
@@ -103,7 +107,7 @@ During the development cycle, three main supporting branches are used:
 
 #### Updating the token:
 
-NOTE: the current token (associated to @DaniBodor) allowing to bypass branch protection will expire on June 20th, 2025. To update the token do the following:
+NOTE: the current token (associated to @DaniBodor) allowing to bypass branch protection will expire on XXXXX. 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.
@@ -115,16 +119,18 @@ 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 .'[dev]'`
-1. Branch from `main` and prepare the branch for the release (e.g., removing the unnecessary files, fix minor bugs if necessary).
+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 <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`).
+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.