diff --git a/.github/workflows/reusable-version-branch.yml b/.github/workflows/reusable-version-branch.yml new file mode 100644 index 00000000..be60ded4 --- /dev/null +++ b/.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 diff --git a/.github/workflows/version-branch.yml b/.github/workflows/version-branch.yml new file mode 100644 index 00000000..086db401 --- /dev/null +++ b/.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 diff --git a/CHANGES.rst b/CHANGES.rst index c7c9c190..6e1b7799 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,11 @@ Changelog ========= +Version 1.2.0 [Unreleased] +-------------------------- + +Work in progress. + Version 1.1.1 [2024-11-20] -------------------------- diff --git a/docs/developer/index.rst b/docs/developer/index.rst index e3e53c4d..95859cfa 100644 --- a/docs/developer/index.rst +++ b/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: diff --git a/docs/developer/reusable-workflows.rst b/docs/developer/reusable-workflows.rst new file mode 100644 index 00000000..322592e9 --- /dev/null +++ b/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= # e.g. 1.2 + git fetch origin + git checkout $VERSION + git reset --hard origin/master + git push origin $VERSION --force-with-lease diff --git a/openwisp_utils/__init__.py b/openwisp_utils/__init__.py index 5327dc4c..60e34a65 100644 --- a/openwisp_utils/__init__.py +++ b/openwisp_utils/__init__.py @@ -1,4 +1,4 @@ -VERSION = (1, 1, 1, 'final') +VERSION = (1, 2, 0, 'alpha') __version__ = VERSION # alias