feat: change the release and staging branching model (#900)

This pull request refactors the current branching model to improve development and address several challenges associated with using staging as the default base branch for pull requests. With this update, main will serve as the base branch for pull requests, containing active development changes, while releases will be triggered upon merging pull requests into the newly created release branch.

Author: behnazh

.github/dependabot.yaml

@@ -13,7 +13,7 @@ updates:
     prefix-development: chore
     include: scope
   open-pull-requests-limit: 13
-  target-branch: staging
+  target-branch: main
   # Add additional reviewers for PRs opened by Dependabot. For more information, see:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers
   # reviewers:
@@ -28,7 +28,7 @@ updates:
     prefix-development: chore
     include: scope
   open-pull-requests-limit: 13
-  target-branch: staging
+  target-branch: main
   # Add additional reviewers for PRs opened by Dependabot. For more information, see:
   # https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers
   # reviewers:

.github/workflows/_generate-rebase.yaml

@@ -1,5 +1,5 @@
-# Automatically rebase one branch on top of another; usually staging on top
-# of main after a new package version was published.
+# Automatically rebase one branch on top of another; usually main on top
+# of release after a new package version was published.
 
 name: Rebase branch
 on:

.github/workflows/codeql-analysis.yaml

@@ -5,12 +5,12 @@ name: CodeQL
 on:
   push:
     branches:
+    - release
     - main
-    - staging
   pull_request:
     branches:
+    - release
     - main
-    - staging
     # Avoid unnecessary scans of pull requests.
     paths:
     - '**/*.py'

.github/workflows/release.yaml

@@ -1,12 +1,12 @@
 # We run checks on pushing to the specified branches.
-# Pushing to main also triggers a release.
+# Pushing to release also triggers a release.
 
 name: Check and Release
 on:
   push:
     branches:
+    - release
     - main
-    - staging
 permissions:
   contents: read
 
@@ -19,11 +19,11 @@ jobs:
     with:
       disable-pip-audit: ${{ vars.DISABLE_PIP_AUDIT == 'true' }}
 
-  # On pushes to the 'main' branch create a new release by bumping the version
+  # On pushes to the 'release' branch create a new release by bumping the version
   # and generating a change log. That's the new bump commit and associated tag.
   bump:
     needs: check
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/release'
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -77,7 +77,7 @@ jobs:
 
   # When triggered by the version bump commit, build the package and publish the release artifacts.
   build:
-    if: github.ref == 'refs/heads/main' && startsWith(github.event.commits[0].message, 'bump:')
+    if: github.ref == 'refs/heads/release' && startsWith(github.event.commits[0].message, 'bump:')
     uses: ./.github/workflows/_build.yaml
     permissions:
       contents: read
@@ -256,19 +256,19 @@ jobs:
     secrets:
       REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
 
-  # After the bump commit was pushed to the main branch, rebase the staging branch
-  # (to_head argument) on top of the new main branch (from_base argument), to keep
+  # After the bump commit was pushed to the release branch, rebase the main branch
+  # (to_head argument) on top of the new release branch (from_base argument), to keep
   # the histories of both branches in sync.
-  rebase_staging:
+  rebase_main:
     # if: ${{ false }}
     needs: [release]
-    name: Rebase staging branch on main
+    name: Rebase main branch on release
     uses: ./.github/workflows/_generate-rebase.yaml
     permissions:
       contents: read
     with:
-      to-head: staging
-      from-base: origin/main
+      to-head: main
+      from-base: origin/release
       git-user-name: jenstroeger
       git-user-email: jenstroeger@users.noreply.github.com
     secrets:

.github/workflows/sync-with-upstream.yaml

@@ -35,7 +35,7 @@ jobs:
       with:
         token: ${{ secrets.REPO_ACCESS_TOKEN }}
         fetch-depth: 0
-        ref: staging
+        ref: main
         path: repo
 
     - name: Sync with template
@@ -84,7 +84,7 @@ jobs:
             git push --set-upstream origin "$BRANCH_NAME"
 
             # Create the pull request.
-            gh pr create --base staging --head "$BRANCH_NAME" --title "chore: sync with template $LATEST_VERSION" --body "This PR was generated automatically."
+            gh pr create --base main --head "$BRANCH_NAME" --title "chore: sync with template $LATEST_VERSION" --body "This PR was generated automatically."
 
           fi
         fi

README.md

@@ -82,6 +82,8 @@ If you’d like to start your own Python project from scratch, you can either co
 
 - Rename the `src/package/` folder to whatever your own package’s name will be, adjust the Github Actions in `.github/workflows/`, and review the `Makefile`, `pyproject.toml`, `.pre-commit-config.yaml` files as well as the unit tests accordingly. **Note**: by default all Actions run on three different host types (Linux, MacOS, and Windows) whose [rates vary widely](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions#minute-multipliers), so make sure that you disable or budget accordingly if you’re in a private repository!
 
+- A new protected `release` branch, should be created if it doesn't already exist. This branch should be configured with appropriate security policies and essential checks to ensure the integrity and stability of the release process.
+
 - Adjust the content of the `pyproject.toml` file according to your needs, and make sure to fill in the project URL, maintainer and author information too. Don’t forget to reset the package’s version number in `src/package/__init__.py`.
 
 - If you import packages that do not provide type hints into your new repository, then `mypy` needs to be configured accordingly: add these packages to the `pyproject.toml` file using the [`ignore_missing_imports`](https://mypy.readthedocs.io/en/stable/config_file.html#confval-ignore_missing_imports) option.
@@ -141,7 +143,7 @@ make upgrade
 Using the pre-commit tool and its `.pre-commit-config.yaml` configuration, the following git hooks are active in this repository:
 
 - When committing code, a number of [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks) ensure that your code is formatted according to [PEP 8](https://www.python.org/dev/peps/pep-0008/) using the [`black`](https://github.com/psf/black) tool, and they’ll invoke [`flake8`](https://github.com/PyCQA/flake8) (and various plugins), [`pylint`](https://github.com/PyCQA/pylint) and [`mypy`](https://github.com/python/mypy) to check for lint and correct types. There are more checks, but those two are the important ones. You can adjust the settings for these tools in the `pyproject.toml` or `.flake8` configuration files.
-- The [commit message hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks) enforces [conventional commit messages](https://www.conventionalcommits.org/) and that, in turn, enables a _semantic release_ of this package on the Github side: upon merging changes into the `main` branch, the [release action](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/release.yaml) uses the [Commitizen tool](https://commitizen-tools.github.io/commitizen/) to produce a [changelog](https://en.wikipedia.org/wiki/Changelog) and it computes the next version of this package and publishes a release — all based on the commit messages of a release.
+- The [commit message hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks) enforces [conventional commit messages](https://www.conventionalcommits.org/) and that, in turn, enables a _semantic release_ of this package on the Github side: upon merging changes into the `release` branch, the [release action](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/release.yaml) uses the [Commitizen tool](https://commitizen-tools.github.io/commitizen/) to produce a [changelog](https://en.wikipedia.org/wiki/Changelog) and it computes the next version of this package and publishes a release — all based on the commit messages of a release.
 - Using a [pre-push hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_other_client_hooks) this package is also set up to run [`pytest`](https://github.com/pytest-dev/pytest); in addition, the [`coverage`](https://github.com/nedbat/coveragepy) plugin makes sure that _all_ of your package’s code is covered by tests and [Hypothesis](https://hypothesis.works/) is already installed to help with generating test payloads.
 - The [`actionlint`](https://github.com/Mateusz-Grzelinski/actionlint-py) hook is set up to lint GitHub Actions workflows. If [`shellcheck`](https://github.com/koalaman/shellcheck) is installed on the system, `actionlint` runs `shellcheck` to lint the `run` steps in GitHub Actions. Note that `shellcheck` is available on [Ubuntu GitHub Actions runners](https://github.com/actions/runner-images/blob/main/images/linux/Ubuntu2204-Readme.md) by default.
 
@@ -244,9 +246,9 @@ The [sync-with-upstream.yaml](https://github.com/jenstroeger/python-package-temp
 
 ## Versioning, publishing and changelog
 
-To enable automation for [semantic versioning](https://semver.org/), package publishing, and changelog generation it is important to use meaningful [conventional commit messages](https://www.conventionalcommits.org/)! This package template already has a built-in semantic release support enabled which is set up to take care of all three of these aspects — every time changes are pushed to the `main` branch.
+To enable automation for [semantic versioning](https://semver.org/), package publishing, and changelog generation it is important to use meaningful [conventional commit messages](https://www.conventionalcommits.org/)! This package template already has a built-in semantic release support enabled which is set up to take care of all three of these aspects — every time changes are pushed to the `release` branch.
 
-With every package release, a new `bump:` commit is pushed to the `main` branch and tagged with the package’s new version. In addition, the `staging` branch (which this repository uses to stage merged pull requests into for the next release) is rebased on top of the updated `main` branch automatically, so that subsequent pull requests can be merged while keeping a [linear history](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-linear-history).
+With every package release, a new `bump:` commit is pushed to the `release` branch and tagged with the package’s new version. In addition, the `main` branch (which this repository uses to stage merged pull requests into for the next release) is rebased on top of the updated `release` branch automatically, so that subsequent pull requests can be merged while keeping a [linear history](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-linear-history).
 
 If you’d like to receive Slack notifications whenever a new release is published, follow the comments in the [Release Notification](https://github.com/jenstroeger/python-package-template/tree/main/.github/workflows/_release-notifications.yaml) Action and set up a Slack bot by following [the instructions here](https://github.com/slackapi/slack-github-action#setup-2).