[feature] Added guided release tool #497

Dhanus3133 · 2025-07-28T04:46:31Z

Closes #496

coveralls · 2025-07-28T04:54:51Z

coverage: 97.365% (+1.3%) from 96.029%
when pulling 94fccdb on feat/496-changes-gen
into f95b1ae on master.

nemesifier

Looks like it's slowly moving in the right direction.

See my comments below.

tests/test_generate_changelog.py

nemesifier · 2025-08-07T13:11:51Z

tests/test_generate_changelog.py

+            Changelog
+            =========
+
+            [unreleased]


There's the version and date?

tests/test_generate_changelog.py

nemesifier

Great to see progress on this one! 👍

See my comments below and in the rest of the PR.

How can the script be used? We need to summarize the key points of this logic in the docs, please add a new page in the dev section. See other similar pages for reference, eg: QA checks, Re-usable GitHub Actions and Workflows.
Why did you place the files into /releaser instead of openwisp_utils/releaser?
It's not necessarily wrong but I want to know if there was a specific purpose for this? It could make sense to ship this logic only during development and not for production code.
Where is the logic which makes the script available to users installing this module? See openwisp-qa-check, openwisp-qa-format, openwisp-pre-push-hook, checkmigrations and check_commit_message for reference.

releaser/tests/test_version_bumping.py

setup.py

releaser/github.py

releaser/release.py

nemesifier · 2025-08-11T20:12:08Z

releaser/tests/samples/commits/full_changelog.txt

+[deps] Update django requirement from ~=4.0 to ~=4.1
+[deps] Update requests requirement from <2.25 to <2.30
+[test] Add tests for the new feature
+[deps] Update django requirement from ~=3.2 to ~=4.0


Can you include in these samples full git log output which inlcudes extended commit messages (spanning multiple lines)? We need to make sure the change log incorporates the full git log.

nemesifier · 2025-08-18T16:28:15Z

docs/developer/index.rst

    ./test-utilities.rst
    ./other-utilities.rst
    ./reusable-github-utils.rst
+    ./releaser-script.rst


Suggested change

./releaser-script.rst

./releaser-tool.rst

Did you forget to update this?

nemesifier · 2025-08-18T16:28:22Z

docs/developer/releaser-script.rst

@@ -0,0 +1,91 @@
+The Releaser Script


Suggested change

The Releaser Script

The Releaser Tool

nemesifier · 2025-08-18T16:28:31Z

docs/developer/releaser-script.rst

+
+.. include:: ../partials/developer-docs.rst
+
+This script automates the project release workflow, from changelog


Suggested change

This script automates the project release workflow, from changelog

This tool automates the project release workflow, from change log

nemesifier · 2025-08-18T16:34:06Z

setup.py

+            "git-cliff~=2.10.0",
+            "questionary~=2.1.0",
+            "pypandoc~=1.15",
+            "pypandoc-binary~=1.15",


If the user hasn't installed these by running pip install openwisp-utils[releaser], the script will fail right? Are you checking for these in the pre-requisites check?

Yes, it fails.

nemesifier · 2025-08-18T16:45:23Z

openwisp_utils/releaser/tests/test_ai_summary.py

+    result = get_gpt_summary(SAMPLE_CONTENT, "rst", token=None)
+    assert result == SAMPLE_CONTENT
+    mock_print.assert_called_with(
+        "⚠️ CHATGPT_TOKEN environment variable is not set. Skipping AI summary.",


Using OPENAI_API_KEY may be a better name here, see:

nemesifier

Summary of manual testing.

Resilience

We need the tool to be resilient: any step, especially the network requests, can fail. If a failure happens after 50% of progress, we can't repeat the process, rolling back or recovering is time consuming. The tool must be ready to catch failures and recommend manual actions.

I recommend adding something like retriable_request, a function that can execute another function and provide a fallback action to recommend in case of errors.
This means that it would be great to make sure every step in the process has its own function.

Error ouput

When there's an unexpected error/exception, it would be good to print out as much error information as possible to ease debugging.

nemesifier · 2025-08-18T18:46:34Z

openwisp_utils/releaser/release.py

+            else:
+                print("Skipping changelog port. Please remember to do it manually.")
+
+    except KeyboardInterrupt:


Can we move these try/except to the if __name__ == "__main__": block?

nemesifier · 2025-08-18T18:47:46Z

openwisp_utils/releaser/release.py

+    return config, gh
+
+
+def get_gpt_summary(content, file_format, token):


We could use a more generic naming here:

Suggested change

def get_gpt_summary(content, file_format, token):

def get_ai_summary(content, file_format, token):

nemesifier · 2025-08-18T18:48:11Z

openwisp_utils/releaser/release.py

+from openwisp_utils.releaser.github import GitHub
+from openwisp_utils.releaser.version import bump_version, get_current_version
+
+MAIN_BRANCHES = ["main", "master"]


Master is more common:

Suggested change

MAIN_BRANCHES = ["main", "master"]

MAIN_BRANCHES = ["master", "main"]

nemesifier · 2025-08-18T18:51:04Z

openwisp_utils/releaser/release.py

+        )
+
+
+def main():


Can we move this to the top to ease readability?

nemesifier · 2025-08-18T18:51:21Z

openwisp_utils/releaser/release.py

+            return content
+
+
+def determine_new_version(current_version_str, current_type, is_bugfix):


Why not move it to version.py?

nemesifier · 2025-08-18T18:53:11Z

openwisp_utils/releaser/release.py

+    run_git_cliff,
+)
+from openwisp_utils.releaser.github import GitHub
+from openwisp_utils.releaser.version import bump_version, get_current_version


I like how you separated logic in different files here.

I recommend checking if it moving more of the functions from this file to other files could improve readability.

nemesifier · 2025-08-18T18:53:36Z

openwisp_utils/releaser/generate_changelog.py

@@ -0,0 +1,186 @@
+import importlib.resources as pkg_resources


can we rename this file to just changelog.py?

nemesifier · 2025-08-18T18:56:03Z

releaser.toml

@@ -0,0 +1,3 @@
+repo = "Dhanus3133/openwisp-utils"


Is this file still needed?

nemesifier · 2025-08-19T22:30:58Z

docs/developer/index.rst

    ./test-utilities.rst
    ./other-utilities.rst
    ./reusable-github-utils.rst
+    ./releaser-script.rst


Did you forget to update this?

nemesifier · 2025-08-19T22:33:20Z

openwisp_utils/releaser/tests/samples/commits/full_changelog.txt

@@ -0,0 +1,16 @@
+[feature] Generate CHANGES.rst automatically #496
+[change] Switched to prettier for CSS/JS linting #367


What if a commit message spans multiple lines? Are we omitting the long description? Let's make sure long descriptions are included please.

nemesifier

I tried this now for this: openwisp/ansible-wireguard-openwisp#71

The releaser.toml file got included in the commit:

Is this normal? I don't think this should happen.

I'll remove it manually for now.

Dhanus3133 · 2025-08-22T20:13:19Z

I don’t think releaser.toml is created automatically. From what I remember in the call, we were testing with the previous implementation (releaser.toml way), so I believe it was created at that time. Are you sure if there were no unstaged changes already present before running the release now?

PS: I think we could also add logic to notify the user about other changes that are available locally ater the checks.

nemesifier

@Dhanus3133

I don’t think releaser.toml is created automatically. From what I remember in the call, we were testing with the previous implementation (releaser.toml way), so I believe it was created at that time. Are you sure if there were no unstaged changes already present before running the release now?

PS: I think we could also add logic to notify the user about other changes that are available locally ater the checks.

I had to make some changes after the changes were created before proceeding: I had to reformat files due to the fact that we updated openwisp-utils to use prettier also for JSON and YAML files. So I pushed this change first, then I went ahead with the process after verifying the change log appeared.

Question: is it possible to avoid creating the file at all or is it really needed? In the worst case scenario we can add a .gitignore file in each repo although this will be time consuming.

Ansible WLP testing error due to rst syntax issue

I tried this here: https://github.com/openwisp/ansible-openwisp-wifi-login-pages.

This is what happened:

Warning: Could not format content with `docstrfmt`.
WARNING: File "/tmp/tmpbw5uy424.rst", line 27:
Bullet list ends without a blank line; unexpected unindent.
Failed to format '/tmp/tmpbw5uy424.rst'
1 file was checked.
Done, but 1 error occurred ❌💥❌

This is probably caused by a restructured text syntax error somewhere which is crashing docstrfmt. However, it's not clear whether I can recover from this error manually.

When this happens, it would be good to let the user know about the problem and return the error but we should also return the unformatted change log output, so the user can try figuring out where the problem is or in the worse case scenario overcome the issue by accepting the unformatted change log and then solving it manually before the final acceptance.

Dhanus3133 · 2025-08-22T20:52:44Z

Question: is it possible to avoid creating the file at all or is it really needed? In the worst case scenario we can add a .gitignore file in each repo although this will be time consuming.

I am sure it was not created automatically. I tested out locally now. You can check this Dhanus3133/ansible-wireguard-openwisp#1 out.

Dhanus3133 · 2025-08-22T21:08:34Z

Ansible WLP testing error due to rst syntax issue

I tried this here: https://github.com/openwisp/ansible-openwisp-wifi-login-pages.

This is what happened:
Warning: Could not format content with `docstrfmt`.
WARNING: File "/tmp/tmpbw5uy424.rst", line 27:
Bullet list ends without a blank line; unexpected unindent.
Failed to format '/tmp/tmpbw5uy424.rst'
1 file was checked.
Done, but 1 error occurred ❌💥❌

Weird, I tried this on my fork now Dhanus3133/ansible-openwisp-wifi-login-pages#1 didn't seem to encounter this issue.

When this happens, it would be good to let the user know about the problem and return the error but we should also return the unformatted change log output, so the user can try figuring out where the problem is or in the worse case scenario overcome the issue by accepting the unformatted change log and then solving it manually before the final acceptance.

Okay, understood.

nemesifier · 2025-08-23T16:28:40Z

Question: is it possible to avoid creating the file at all or is it really needed? In the worst case scenario we can add a .gitignore file in each repo although this will be time consuming.

I am sure it was not created automatically. I tested out locally now. You can check this Dhanus3133/ansible-wireguard-openwisp#1 out.

Maybe it was a leftover from one of our previous tests.

I hope you can make the initial change log generation robust to failures in case docstrfmt crashes.

Closes #496

… porting changelog

nemesifier

My last attempt worked smoothly, I'll be doing a few more releases before merging but it looks really good now, thanks!

pandafy · 2025-10-23T16:36:20Z

openwisp_utils/releaser/release.py

+    changelog_date_str = datetime.now().strftime("%Y-%m-%d")
+    tag_date_str = datetime.now().strftime("%d-%m-%Y")


@nemesifier did you notice that we have two different date formats for tag and changelog?

No, but it's not a big deal. Git releases are still readable.

Dhanus3133 force-pushed the feat/496-changes-gen branch from cc90865 to 3a7aa9a Compare July 28, 2025 04:50

nemesifier reviewed Aug 7, 2025

View reviewed changes

nemesifier requested changes Aug 11, 2025

View reviewed changes

nemesifier changed the title ~~[feature] Generate CHANGES.rst automatically~~ [feature] Added guided release tool Aug 11, 2025

nemesifier assigned Dhanus3133 Aug 11, 2025

nemesifier added the enhancement label Aug 11, 2025

nemesifier reviewed Aug 18, 2025

View reviewed changes

nemesifier reviewed Aug 19, 2025

View reviewed changes

This was referenced Aug 20, 2025

[docs] Added guided releaser media images #505

Merged

[chores] Added spelling wordlist for releaser tool guide openwisp/openwisp-docs#230

Merged

nemesifier reviewed Aug 22, 2025

View reviewed changes

nemesifier requested changes Aug 22, 2025

View reviewed changes

Dhanus3133 added 11 commits August 30, 2025 16:24

[feature] Generate CHANGES.rst automatically #496

fd4bf4c

Closes #496

[feat] Added git-cliff config

001fef8

[chores] Improve commit_parsers regex

1ecdcec

[chore] Add python script to handle dependencies section

5e56828

[tests] Add basic changelog tests

6090373

[fix] QA

ec3e8a5

[chore] Review changes

3085f14

[change] Add git-cliff package

c6c9469

[fix] Tests

a45bf94

[tests] Refactor tests

8e5ca3c

[tests] Update test_generate_changelog

fbf436a

Dhanus3133 and others added 17 commits August 30, 2025 16:24

[feature] Releaser script

84ce3a7

[tests] Add dummy token

4537c42

[chore] All review changes

092eb2e

[fix] Lower case request type for retryable_request

d07ae02

[fix] Re-read changelog from file to use user's edits for release and…

6beab1e

… porting changelog

[fix] QA

cac8943

[chore] Revert back the request method

33bb14b

[chore] Discussed changes

9a6c45c

[chores] Fixed minor f var string interpolation bug

823590d

[chore] Improved test coverage and review changes

a590e94

[feature] Handle request errors

ef5ec84

[tests] Support multi-line commit messages in changelog tests

e09c2ef

[docs] Update docs

f318a65

[chore] Improvements

85ad6ac

[fix] QA checks

c89eabf

[docs] Update terms

5d233d4

[feature] Add interactive recovery for docstrfmt errors

00a9816

Dhanus3133 force-pushed the feat/496-changes-gen branch from ac09af9 to 00a9816 Compare August 30, 2025 10:56

[fix] Handle Version header missing on some modules

ab9ba29

nemesifier added this to 25.09 Release Sep 2, 2025

nemesifier moved this to In progress in 25.09 Release Sep 2, 2025

nemesifier moved this from In progress to Ready for review/testing in 25.09 Release Sep 3, 2025

nemesifier reviewed Sep 9, 2025

View reviewed changes

Merge branch 'master' into feat/496-changes-gen

94fccdb

nemesifier approved these changes Sep 30, 2025

View reviewed changes

nemesifier merged commit ef70d79 into master Sep 30, 2025
20 checks passed

nemesifier deleted the feat/496-changes-gen branch September 30, 2025 23:09

github-project-automation bot moved this from Ready for review/testing to Done in 25.09 Release Sep 30, 2025

pandafy reviewed Oct 23, 2025

View reviewed changes


		.. include:: ../partials/developer-docs.rst

		This script automates the project release workflow, from changelog

	This script automates the project release workflow, from changelog
	This tool automates the project release workflow, from change log

		return config, gh


		def get_gpt_summary(content, file_format, token):

	def get_gpt_summary(content, file_format, token):
	def get_ai_summary(content, file_format, token):

	MAIN_BRANCHES = ["main", "master"]
	MAIN_BRANCHES = ["master", "main"]

		return content


		def determine_new_version(current_version_str, current_type, is_bugfix):

		@@ -0,0 +1,186 @@
		import importlib.resources as pkg_resources

		@@ -0,0 +1,16 @@
		[feature] Generate CHANGES.rst automatically #496
		[change] Switched to prettier for CSS/JS linting #367

		changelog_date_str = datetime.now().strftime("%Y-%m-%d")
		tag_date_str = datetime.now().strftime("%d-%m-%Y")

Uh oh!

[feature] Added guided release tool #497

[feature] Added guided release tool #497

Uh oh!

Conversation

Dhanus3133 commented Jul 28, 2025

Uh oh!

coveralls commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nemesifier left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nemesifier left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nemesifier left a comment

Choose a reason for hiding this comment

Resilience

Error ouput

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nemesifier Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nemesifier left a comment

Choose a reason for hiding this comment

Uh oh!

Dhanus3133 commented Aug 22, 2025

Uh oh!

nemesifier left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Ansible WLP testing error due to rst syntax issue

Uh oh!

Dhanus3133 commented Aug 22, 2025

coveralls commented Jul 28, 2025 •

edited

Loading

nemesifier Aug 18, 2025 •

edited

Loading

nemesifier left a comment •

edited

Loading