Merge branch 'master' into issues/367-switch-to-prettier

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

@@ -0,0 +1,61 @@
+name: Replicate Commits to Version Branch
+
+on:
+  workflow_call:
+    inputs:
+      module_name:
+        description: 'The name of the module'
+        required: true
+        type: string
+      install_package:
+        description: 'Whether to install the package'
+        required: false
+        type: boolean
+        default: false
+
+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.10'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+
+    - name: Install package if required
+      if: ${{ inputs.install_package }}
+      run: |
+        pip install .
+
+    - 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

CHANGES.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+Version 1.2.0 [Unreleased]
+--------------------------
+
+Work in progress.
+
 Version 1.1.1 [2024-11-20]
 --------------------------
 

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,59 @@
+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
+          # Whether to install the Python package. Defaults to false.
+          install_package: true
+
+.. 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

openwisp_utils/__init__.py

@@ -1,4 +1,4 @@
-VERSION = (1, 1, 1, 'final')
+VERSION = (1, 2, 0, 'alpha')
 __version__ = VERSION  # alias