[ci] Added GitHub workflow to replicate commits to version branch

Created re-usable workflow for replication commits from the
master branch to version branch.

Author: pandafy

.github/workflows/reusable-version-branch.yml

@@ -0,0 +1,51 @@
+name: Replicate Commits to Version Branch
+
+on:
+  workflow_call:
+    inputs:
+      module_name:
+        description: 'The name of the module'
+        required: true
+        type: string
+
+jobs:
+  replicate:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+
+    - name: Get version
+      id: get_version
+      run: |
+        VERSION=$(python -c "
+        from ${{ inputs.module_name }} import VERSION
+        print(f'{VERSION[0]}.{VERSION[1]}')
+        ")
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+    - name: Configure Git
+      run: |
+        git config --global user.name 'github-actions[bot]'
+        git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+
+    - name: Rebase changes onto version branch
+      run: |
+        if git ls-remote --heads origin $VERSION | grep -sw $VERSION; then
+          git fetch origin --unshallow
+          git checkout -b $VERSION origin/$VERSION
+          git rebase origin/master
+        else
+          git checkout -b $VERSION
+        fi
+        git push origin $VERSION

.github/workflows/version-branch.yml

@@ -0,0 +1,12 @@
+name: Replicate Commits to Version Branch
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  version-branch:
+    uses: openwisp/openwisp-utils/.github/workflows/reusable-version-branch.yml@master
+    with:
+      module_name: openwisp_utils

docs/developer/index.rst

@@ -16,6 +16,7 @@ Developer Docs
     ./admin-utilities.rst
     ./test-utilities.rst
     ./other-utilities.rst
+    ./reusable-workflows.rst
 
 Other useful resources:
 

docs/developer/reusable-workflows.rst

@@ -0,0 +1,57 @@
+Re-usable GitHub Workflows
+==========================
+
+Replicate Commits to Version Branch
+-----------------------------------
+
+This re-usable workflow replicates commits from the ``master`` branch to a
+version branch. The version branch name is derived from the version of the
+Python package specified in the workflow.
+
+Version branches are essential during development to ensure that each
+OpenWISP module depends on compatible versions of its OpenWISP
+dependencies. Without version branches, modules depending on the
+``master`` branch of other modules may encounter errors, as the ``master``
+branch could include future changes that are incompatible with previous
+versions. This makes it impossible to build a specific commit reliably
+after such changes.
+
+To address this, we use version branches so that each module can depend on
+a compatible version of its dependencies during development. Managing
+these version branches manually is time-consuming, which is why this
+re-usable GitHub workflow automates the process of keeping version
+branches synchronized with the ``master`` branch.
+
+You can invoke this workflow from another workflow using the following
+example:
+
+.. code-block:: yaml
+
+    name: Replicate Commits to Version Branch
+
+    on:
+      push:
+        branches:
+          - master
+
+    jobs:
+      version-branch:
+        uses: openwisp/openwisp-utils/.github/workflows/reusable-version-branch.yml@master
+        with:
+          # The name of the Python package (required)
+          module_name: openwisp_utils
+
+.. note::
+
+    If the ``master`` branch is force-pushed, this workflow will fail due
+    to conflicts. To resolve this, you must manually synchronize the
+    version branch with the ``master`` branch. You can use the following
+    commands to perform this synchronization:
+
+    .. code-block:: bash
+
+        VERSION=<enter-version-number> # e.g. 1.2
+        git fetch origin
+        git checkout $VERSION
+        git reset --hard origin/master
+        git push origin $VERSION --force-with-lease