[feature] Added guided release tool

.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
         run: |
           pip install -U pip wheel setuptools
           pip install -U -r requirements-test.txt
-          pip install -e .[qa,rest,selenium]
+          pip install -e .[qa,rest,selenium,releaser]
           pip install ${{ matrix.django-version }}
           sudo npm install -g prettier
 

docs/developer/index.rst

@@ -17,6 +17,7 @@ Developer Docs
     ./test-utilities.rst
     ./other-utilities.rst
     ./reusable-github-utils.rst
+    ./releaser-tool.rst
 
 Other useful resources:
 

docs/developer/releaser-tool.rst

@@ -0,0 +1,112 @@
+The Releaser Tool
+=================
+
+.. include:: ../partials/developer-docs.rst
+
+This interactive command-line tool streamlines the entire project release
+workflow, from generating a change log to creating a draft release on
+GitHub. It is designed to be resilient, allowing you to recover from
+common failures like network errors without starting over.
+
+Prerequisites
+-------------
+
+**1. Installation**
+~~~~~~~~~~~~~~~~~~~
+
+Install the releaser and all its Python dependencies from the root of the
+``openwisp-utils`` repository:
+
+.. code-block:: shell
+
+    pip install .[releaser]
+
+**2. GitHub Personal Access Token**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tool requires a GitHub Fine-grained Personal Access Token to create
+pull requests, tags, and releases on your behalf.
+
+1. Navigate to **Settings** > **Developer settings** > **Personal access
+   tokens** > **Fine-grained tokens**.
+2. Click **Generate new token**.
+3. Give it a descriptive name (e.g., "OpenWISP Releaser") and set an
+   expiration date.
+4. Under **Repository access**, choose either **All repositories** or
+   select the specific repositories you want to manage.
+5. Under **Permissions**, click on **Add permissions**.
+6. Grant the following permissions:
+
+   - **Metadata**: Read-only
+   - **Pull requests**: Read & write
+
+7. Generate the token and export it as an environment variable:
+
+.. code-block:: shell
+
+    export OW_GITHUB_TOKEN="github_pat_YourTokenGoesHere"
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-utils/media/docs/releaser/github-access-token.png
+    :alt: Screenshot showing the required repository permissions for a new fine-grained GitHub Personal Access Token.
+
+**3. OpenAI API Token (Optional)**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tool can use GPT-4o to generate a human-readable summary of your
+change log. If you wish to use this feature, export your OpenAI API key:
+
+.. code-block:: shell
+
+    export OPENAI_CHATGPT_TOKEN="sk-YourOpenAITokenGoesHere"
+
+Usage
+-----
+
+Navigate to the root directory of the project you want to release and run
+the following command:
+
+.. code-block:: shell
+
+    python -m openwisp_utils.releaser
+
+The Interactive Workflow
+------------------------
+
+The tool will guide you through each step. Here are the key interactions:
+
+**1. Version Confirmation** The tool will detect the current version and
+suggest the next one. You can either accept the suggestion or enter a
+different version manually.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-utils/media/docs/releaser/version-confirmation.png
+    :alt: Screenshot showing the tool suggesting a new version number and asking for user confirmation.
+
+**2. Change Log Generation & Review** A changelog is generated from your
+recent commits. If an OpenAI token is configured, the tool will offer to
+generate a more readable summary. You will then be shown the final
+changelog block and asked to accept it before the files are modified.
+
+**3. Resilient Error Handling** If any network operation fails (e.g.,
+creating a pull request), the tool won't crash. Instead, it will prompt
+you to **Retry**, **Skip** the step (with manual instructions), or
+**Abort**.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-utils/media/docs/releaser/error-handling.png
+    :alt: Screenshot of the interactive prompt after a network error, showing Retry, Skip, and Abort options.
+
+Summary of Automated Steps
+--------------------------
+
+Once you confirm the change log, the tool automates the rest of the
+process:
+
+1. Updates the version number in your project's ``__init__.py``.
+2. Writes the new release notes to your ``CHANGES.rst`` or ``CHANGES.md``
+   file.
+3. Creates a ``release/<version>`` branch and commits the changes.
+4. Pushes the new branch to GitHub.
+5. Creates a pull request and waits for you to merge it.
+6. Once merged, it creates and pushes a signed git tag.
+7. Finally, it creates a draft release on GitHub with the changelog notes.
+8. If releasing a bugfix, it offers to port the changelog to the ``main``
+   or ``master`` branch.

openwisp_utils/cliff.toml

@@ -0,0 +1,113 @@
+[changelog]
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+body = """
+{% if version %}\
+    Version {{ version | trim_start_matches(pat="v") }}  [{{ timestamp | date(format="%Y-%m-%d") }}]
+    -------------------------------------
+{% else %}\
+    [unreleased]
+    ------------
+{% endif %}\
+{#- Features block #}
+{% for group, commits in commits | group_by(attribute="group") %}
+    {% set clean_group = group | striptags | trim %}
+    {%- if clean_group == "Features" -%}
+        {{ clean_group | upper_first }}
+        ~~~~~~~~
+        {% for commit in commits %}
+            - {{ commit.message | split(pat="\n") | first | split(pat="]") | nth(n=1) | trim | upper_first }}
+        {%- endfor -%}
+    {%- endif -%}
+{%- endfor -%}
+{#- Changes block -#}
+{% for group, commits in commits | group_by(attribute="group") %}
+    {% set clean_group = group | striptags | trim -%}
+        {% if clean_group == "Backward-incompatible changes" or clean_group == "Other changes" or clean_group == "Dependencies" -%}
+            Changes
+            ~~~~~~~
+            {% break %}
+        {% endif -%}
+{% endfor %}
+{%- for group, commits in commits | group_by(attribute="group") %}
+    {% set clean_group = group | striptags | trim -%}
+    {%- if clean_group == "Backward-incompatible changes" -%}
+        {{ clean_group | upper_first }}
+        +++++++++++++++++++++++++++++++++
+        {% for commit in commits %}
+            - {{ commit.message | split(pat="\n") | first | split(pat="]") | nth(n=1) | trim | upper_first }}
+        {%- endfor -%}
+    {%- endif -%}
+{%- endfor -%}
+{% for group, commits in commits | group_by(attribute="group") %}
+    {% set clean_group = group | striptags | trim %}
+    {%- if clean_group == "Other changes" -%}
+        {{ clean_group | upper_first }}
+        +++++++++++++
+        {% for commit in commits %}
+            - {{ commit.message | split(pat="\n") | first | split(pat="]") | nth(n=1) | trim | upper_first }}
+        {%- endfor -%}
+    {% endif %}
+{%- endfor -%}
+{% for group, commits in commits | group_by(attribute="group") %}
+    {%- set clean_group = group | striptags | trim -%}
+    {%- if clean_group == "Dependencies" -%}
+        {{ clean_group | upper_first }}
+        ++++++++++++
+        {% for commit in commits %}
+            - {{ commit.message | split(pat="\n") | first | split(pat="]") | nth(n=1) | trim | upper_first }}
+        {%- endfor -%}
+    {%- endif -%}
+{%- endfor -%}
+{#- Bugfixes block #}
+{%- for group, commits in commits | group_by(attribute="group") -%}
+    {% set clean_group = group | striptags | trim %}
+    {% if clean_group == "Bugfixes" %}
+        {{ clean_group | upper_first }}
+        ~~~~~~~~
+        {% for commit in commits %}
+            - {{ commit.message | split(pat="\n") | first | split(pat="]") | nth(n=1) | trim | upper_first }}
+        {%- endfor -%}
+    {% endif %}
+{% endfor %}
+"""
+
+# remove the leading and trailing space
+trim = true
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = false
+# filter out the commits that are not conventional
+filter_unconventional = false
+# process each line of a commit as an individual commit
+split_commits = false
+# an array of regex based parsers to modify commit messages prior to further processing.
+commit_preprocessors = [
+  { pattern = '#([0-9]+)', replace = '`#$1 <https://github.com/#REPO#/issues/$1>`_' },
+]
+
+# regex for parsing and grouping commits
+commit_parsers = [
+  # Any commits with [skip changelog] in their message will be ignored.
+  { message = "\\[skip changelog\\]", skip = true },
+  # Regex for features, e.g., '[feature]' or '[feature:api]'
+  { message = "^(\\[feature(:[a-zA-Z0-9_-]+)?\\])", group = "<!-- 0 -->Features", strip = "message" },
+  # Regex for backward-incompatible changes, e.g., '[change!]' or '[change:db!]'
+  { message = "^(\\[change(:[a-zA-Z0-9_-]+)?!\\])", group = "<!-- 1 -->Backward-incompatible changes", strip = "message" },
+  # Regex for regular changes, e.g., '[change]' or '[change:ui]'
+  { message = "^(\\[change(:[a-zA-Z0-9_-]+)?\\])", group = "<!-- 2 -->Other changes", strip = "message" },
+  # Regex for dependency updates, e.g., '[deps]' or '[deps:npm]'
+  { message = "^(\\[deps(:[a-zA-Z0-9_-]+)?\\])", group = "<!-- 3 -->Dependencies", strip = "message" },
+  # Regex for bugfixes, e.g., '[fix]' or '[fix:tests]'
+  { message = "^(\\[fix(:[a-zA-Z0-9_-]+)?\\])", group = "<!-- 4 -->Bugfixes", strip = "message" },
+]
+
+# protect breaking changes from being skipped due to matching a skipping commit_parser
+protect_breaking_commits = false
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "newest"

openwisp_utils/releaser/__main__.py

@@ -0,0 +1,22 @@
+import subprocess
+import sys
+
+import requests
+from openwisp_utils.releaser.release import main
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\n\n❌ Release process terminated by user.")
+        sys.exit(1)
+    except (
+        subprocess.CalledProcessError,
+        requests.RequestException,
+        RuntimeError,
+        FileNotFoundError,
+    ) as e:
+        print(f"\n❌ An error occurred: {e}", file=sys.stderr)
+        if isinstance(e, subprocess.CalledProcessError):
+            print(f"Error Details: {e.stderr}", file=sys.stderr)
+        sys.exit(1)