[feature] Automated follow-up alpha version bump PRs

docs/developer/releaser-tool.rst

@@ -59,6 +59,20 @@ the following command:
 
     python -m openwisp_utils.releaser
 
+If the process stops after it creates the release pull request, resume it
+without repeating the version bump or changelog preparation:
+
+.. code-block:: shell
+
+    python -m openwisp_utils.releaser resume https://github.com/owner/repository/pull/123
+
+The resume command watches that release pull request until it is merged
+and then creates any missing downstream artifacts. It reuses an existing
+version tag on the merged base branch, an existing GitHub release for that
+tag, and matching follow-up pull requests instead of creating duplicates.
+A pull request that was closed without merging must be reopened or
+replaced before the release can be resumed.
+
 The Interactive Workflow
 ------------------------
 
@@ -92,11 +106,17 @@ 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.
+       file.
+3. Creates a ``release/<version>`` branch and commits only the updated
+   changelog and detected version file, leaving unrelated worktree changes
+   unstaged.
 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.
+9. If releasing a new feature from a Python or npm project, it offers to
+   bump the version to the next alpha release: it opens a pull request
+   which sets the version to the next minor release with the ``alpha``
+   marker and adds a new ``[unreleased]`` section to the change log.

openwisp_utils/releaser/__main__.py

@@ -1,12 +1,21 @@
+import argparse
 import subprocess
 import sys
 
 import requests
 from openwisp_utils.releaser.release import main
 
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("command", nargs="?", choices=["resume"])
+    parser.add_argument("pr_url", nargs="?")
+    args = parser.parse_args()
+    if args.command == "resume" and not args.pr_url:
+        parser.error("resume requires the release pull request URL")
+    if args.command is None and args.pr_url:
+        parser.error("a pull request URL can only be used with the resume command")
     try:
-        main()
+        main(resume_pr_url=args.pr_url)
     except KeyboardInterrupt:
         print("\n\n❌ Release process terminated by user.")
         sys.exit(1)

openwisp_utils/releaser/github.py

@@ -1,4 +1,5 @@
 import uuid
+from urllib.parse import urlparse
 
 import requests
 from openwisp_utils.utils import retryable_request as utils_retryable_request
@@ -38,11 +39,60 @@ def create_pr(self, head, base, title):
 
     def is_pr_merged(self, pr_url):
         """Checks if a pull request has been merged."""
-        pr_number = pr_url.split("/")[-1]
+        pr_number = pr_url.rstrip("/").split("/")[-1]
         url = f"{self.base_url}/pulls/{pr_number}"
         response = retryable_request(method="get", url=url, headers=self.headers)
         return response.json().get("merged", False)
 
+    def get_pr(self, pr_url):
+        """Returns metadata for a pull request in the configured repository."""
+        parsed_url = urlparse(pr_url)
+        path = parsed_url.path.strip("/").split("/")
+        if (
+            parsed_url.scheme not in {"http", "https"}
+            or parsed_url.netloc != "github.com"
+            or len(path) != 4
+            or "/".join(path[:2]) != self.repo
+            or path[2] != "pull"
+            or not path[3].isdigit()
+        ):
+            raise ValueError(
+                "The pull request URL must belong to the configured GitHub repository."
+            )
+        pr_number = path[3]
+        url = f"{self.base_url}/pulls/{pr_number}"
+        response = retryable_request(method="get", url=url, headers=self.headers)
+        return response.json()
+
+    def get_release(self, tag_name):
+        """Returns the release for a tag, or None when it has not been created."""
+        response = retryable_request(
+            method="get",
+            url=f"{self.base_url}/releases/tags/{tag_name}",
+            headers=self.headers,
+            allowed_status_codes=(404,),
+        )
+        if response.status_code == 404:
+            return None
+        return response.json()
+
+    def find_pr(self, head, base, title):
+        """Returns an existing matching pull request, regardless of its state."""
+        response = retryable_request(
+            method="get",
+            url=f"{self.base_url}/pulls",
+            headers=self.headers,
+            params={"state": "all", "base": base, "per_page": 100},
+        )
+        for pull_request in response.json():
+            if (
+                pull_request.get("title") == title
+                and pull_request.get("head", {}).get("ref") == head
+                and pull_request.get("base", {}).get("ref") == base
+            ):
+                return pull_request
+        return None
+
     def create_release(self, tag_name, title, body):
         """Creates a draft release on GitHub."""
         url = f"{self.base_url}/releases"
@@ -54,8 +104,17 @@ def create_release(self, tag_name, title, body):
             "prerelease": False,
         }
         response = retryable_request(
-            method="post", url=url, headers=self.headers, json=payload
+            method="post",
+            url=url,
+            headers=self.headers,
+            json=payload,
+            allowed_status_codes=(422,),
         )
+        if response.status_code == 422:
+            existing_release = self.get_release(tag_name)
+            if existing_release:
+                return existing_release["html_url"]
+            response.raise_for_status()
         return response.json()["html_url"]
 
     def check_pr_creation_permission(self) -> tuple[bool, str]: