feat(ci): add a Rebase Branch workflow to rebase staging on top of main after a package was published

.github/workflows/_generate-rebase.yaml

@@ -0,0 +1,59 @@
+# Automatically rebase one branch on top of another; usually staging on top
+# of main after a new package version was published.
+
+name: Rebase branch
+on:
+  workflow_call:
+    inputs:
+      to_head:
+        type: string
+        required: true
+        description: Branch that is being rebased
+      from_base:
+        type: string
+        required: true
+        description: Base branch
+      git_user_name:
+        required: true
+        type: string
+        description: Name of the git user that rebases and pushes the to_head branch
+      git_user_email:
+        required: true
+        type: string
+        description: Email address of said git user
+    secrets:
+      REPO_ACCESS_TOKEN:
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  rebase:
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Harden Runner
+      uses: step-security/harden-runner@6b3083af2869dc3314a0257a42f4af696cc79ba3 # v2.3.1
+      with:
+        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
+
+    - name: Check out repository
+      uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+      with:
+        fetch-depth: 0
+        token: ${{ secrets.REPO_ACCESS_TOKEN }}
+        ref: ${{ github.ref_name }}
+
+    - name: Do rebase
+      run: |
+        git config --global user.name "$USER_NAME"
+        git config --global user.email "$USER_EMAIL"
+        git checkout "$TO_HEAD"
+        git rebase "$FROM_BASE"
+        git push --force-with-lease
+      env:
+        USER_NAME: ${{ inputs.git_user_name }}
+        USER_EMAIL: ${{ inputs.git_user_email }}
+        TO_HEAD: ${{ inputs.to_head }}
+        FROM_BASE: ${{ inputs.from_base }}

.github/workflows/release.yaml

@@ -251,3 +251,21 @@ jobs:
       git_user_email: [email protected]
     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
+  # the histories of both branches in sync.
+  rebase_staging:
+    # if: ${{ false }}
+    needs: [release]
+    name: Rebase staging branch on main
+    uses: ./.github/workflows/_generate-rebase.yaml
+    permissions:
+      contents: read
+    with:
+      to_head: staging
+      from_base: origin/main
+      git_user_name: jenstroeger
+      git_user_email: [email protected]
+    secrets:
+      REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}

README.md

@@ -233,7 +233,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 merged into 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 `main` 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).
 
 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).