| name | nuitka-changelog |
| description | Use when creating or updating Nuitka changelog entries (hotfix releases like 4.1.3 or upcoming releases) in the Nuitka website repository, by running update-changelog.py to generate the commit prompt and editing site/changelog/Changelog-next.rst. |
Nuitka Website Changelog Updates
This skill covers producing changelog entries in the Nuitka website repository for a hotfix release
(e.g. 4.1.3) or a develop update, based on the git history of the Nuitka repository.
Workflow
-
Generate the prompt:
python3 update-changelog.py 4.1.3 --nuitka-repo ../Nuitka-develop # hotfix
python3 update-changelog.py 4.2 --nuitka-repo ../Nuitka-develop # final release
python3 update-changelog.py 4.2rc3 --nuitka-repo ../Nuitka-develop # pre-release
VERSION is required and must be one of: hotfix X.Y.Z (e.g. 4.1.3), final X.Y (e.g.
4.2), or pre-release X.YrcN (e.g. 4.2rc3). Anything else is rejected.- The line "It currently covers changes up to version ...." tracks the last
VERSION
argument passed to the script and is updated by the script itself, never by hand.
- Running with a
VERSION that is already the documented state yields an empty range, that is
expected.
--website-repo PATH allows running from outside the website repo.--output FILE writes the prompt to a file instead of stdout.- This prints "Processing changelog for: ..." plus a technical writer prompt containing the raw
commit data.
-
Process the prompt: turn every relevant commit into entries in
site/changelog/Changelog-next.rst, following the content rules below. When done, verify
coverage mechanically: extract every unique commit subject from the prompt and check each one
against the changelog, so that no commit is missed by eyeballing.
-
When the entries are done, always run:
./auto-format site/changelog/Changelog-next.rst
The user often edits the file themselves in between. Read the file again before each edit,
preserve their edits, and learn from them.
Pre-release (develop) updates
What differs from the hotfix workflow:
- The range starts at the commit that introduced the last documented version. It may contain commits
already covered by earlier hotfix passes, so skip every commit whose change is already present in
Changelog-next.rst, do not create duplicate entries.
- The script uses
git log --no-merges, so merge commits never appear in the prompt, and skips
release-cycle commits ("New stable release.", "New release cycle.", ...).
- New entries get no
(Fixed in X.Y.Z already.) or (Added in X.Y.Z already.) suffix, and are
appended at the end of their group in each section, keeping the prefix grouping.
- A develop update covers commits up to the release of the version being documented. Commits after a
"New release cycle." commit belong to the next version and go to its changelog instead.
- Develop commits get their own entries even when related work was already announced in a hotfix
entry.
Researching commits
The raw commit data in the prompt includes diffs, but for anything unclear, inspect the actual code
in the Nuitka repository (default ../Nuitka-develop):
git show <hash> # the commit itself
git log --all --oneline --grep=... # related commits
git log --format="%h %ci %s" -1 <hash>
In particular:
- Check whether a changed feature is behind an experimental flag or is the default at the time of
the hotfix, so entries do not claim a regression that is not one (e.g. new style code objects were
--experimental until after 4.1.2).
- Get the actual semantics right, e.g.
_stdlib_module_raises is the list of modules known to
never raise on import.
- Name the actual helpers and options (e.g.
has_builtin_module, --disable-ccache), not vague
descriptions.
Content rules
Categorization
Use only the existing sections of Changelog-next.rst: Bug Fixes, Package Support, New Features,
Optimization, Anti-Bloat, Organizational, Tests, Cleanups. Never add new headings. A section that
stays empty keeps the placeholder - None yet. (with trailing period).
- Fixes for Nuitka itself -> Bug Fixes.
- Package support additions and fixes -> Package Support.
- New abilities -> New Features (use "Added").
- Performance or import-time optimizations -> Optimization.
- Avoided package dependencies -> Anti-Bloat.
- Release process, packaging (RPM, Debian), license, project tooling -> Organizational.
- Test suite changes -> Tests.
- Code quality, tools, styling -> Cleanups.
- Adding new tooling or functional enhancements of quality tools (new checker tools, new autoformat
behaviors, hook behavior changes) -> Organizational, not Cleanups.
- User visible warnings and handling of user options -> UI: prefix (e.g. duplicate data file
warning), placed per its category, usually Organizational or Bug Fixes.
- Release/packaging fixes -> Organizational with Release:, RPM:, or Debian: prefix.
Suffixes for hotfix entries
Since the commits are the hotfix itself, append:
(Fixed in X.Y.Z already.) to fixes.(Added in X.Y.Z already.) to new features and package support additions, using "Added" rather
than "Fixed".
For develop updates, no such suffix unless certain.
Grouping inside Bug Fixes
Bug Fixes consists of groups that must stay separated: one group per hotfix batch (e.g. all 4.1.1
entries) and one group for all develop changes. The different rc versions of a develop cycle do
not form separate groups, they are one develop group. Groups are ordered by time: hotfix batches
first, the develop group last, appended after the existing hotfix groups.
Within each group, keep entries grouped by bold prefix in this order, appending new entries at the
end of their prefix run:
- Generic Python fixes without a prefix.
- Python version fixes:
**Python 3.x:**, **Python 3.x+:**, **Python3:**.
**Standalone:**.**Plugins:**.**Windows:**.**macOS:**.**Linux:** (and **Debian:** as part of the Linux group).- Other non-platform prefixes (e.g.
**Distutils:**, **PGO:**, **Onefile:**, **Report:**,
**Zig:**, **NoGil:**, **UI:**).
- Other platforms (e.g.
**AIX:**) at the end.
Other sections are not grouped this way, but keep items of the same prefix together where it is
natural.
Ordering inside New Features
- An entry that pronounces a Python version as officially supported (e.g. "Python 3.14:
Pronounced Python 3.14 as officially supported.") is always the first entry of New Features.
- Hotfix entries are not grouped together in New Features. Place them by relevance among the
develop entries, keeping their
(Added in X.Y.Z already.) suffix.
Skipping commits
- Skip
fixup! commits entirely, they are folded into the entry of the commit they fix.
- Skip trivial or internal changes without general relevance for users, e.g. fixes to features that
are not yet the default (unless the user says otherwise).
- Never drop a commit whose content is not understood. Instead, check the code, add an entry with
the best possible description, and inform the user about it, so they can decide.
Audience and wording
The audience is the experienced Nuitka and Python user:
- Explain the actual mechanism and the user visible consequence, not just commit-title jargon. E.g.
prefer "compiled coroutines left the send slot result uninitialized when they finished by raising,
so
asyncio could observe garbage values" over "coroutine am_send could return wrong result
values".
- State the mechanism neutrally: describe what was missing rather than over-asserting the failure
mode (e.g. "the output was not used yet", not "was never obtained").
- For fixes, describe the wrong behavior in past tense and the corrected behavior in present tense
("was handling ... incorrectly, now ..."), avoid formulations like "handled X correctly" that put
the fix itself in the past.
- Never state the corrected behavior in past tense: not "Enabled UTF-8 mode", "added handling for",
"avoided permission issues", "no longer crashed", "solved the need", but "Enables UTF-8 mode",
"now handles", "no longer runs into", "no longer crashes", "no longer needs". Past tense is only
for the wrong behavior and for the change event itself ("Added support for", "Renamed").
- Avoid redundancy, do not repeat the topic word within an entry (e.g. "compiler binary was a
symlink" after already naming ccache), and avoid filler phrases like "closing a gap".
- Name the actual helpers and options (e.g.
has_builtin_module).
- Terminology: handlers for runtime situations where something is missing, failing to work (e.g.
certifi not present) are called "non-deployment handler", not "deployment handling".
- For hotfix entries that describe a change of behavior, showing what it was and what it is now can
be done in a code example comment, e.g.
# 4.1: None (bug), 4.1.1: KeyError (correct).
Quoting
- Double backticks for: option names (
--disable-ccache, --mode=dll), module and package names,
environment variables (PYTHON_FROZEN_MODULES), exception, function, and attribute names
(sys.exc_info(), __qualname__), experimental flag names
(--experimental=deferred-annotations), architecture names (x86_64), and Python keywords
(async, await, with).
- Double quotes only for the flavor name
"Python Build Standalone", since that name is highly
misleading. No other flavor names get quoted.
Code examples
When an entry benefits from a code example, place it inside the list item:
- **Python3:** Fix, ... (Fixed in 4.1.1 already.)
.. code:: python
...
./auto-format turns .. code-block:: python into .. code:: python and formats the Python code
inside (e.g. two blank lines between functions).
Improving this skill and the workflow
- Watch for conventions the user applies by editing
Changelog-next.rst themselves or by correcting
entries in prompts during a session.
- When a pattern emerges (wording, grouping, quoting, categorization), infer the intention behind
it, not the concrete case, and propose adding it to this skill and to the style guide embedded in
update-changelog.py.
- Propose such changes to the user rather than silently rewriting rules, the user is the authority
on the conventions.
- When the workflow itself is painful (script location, output handling, etc.), suggest improvements
to
update-changelog.py as well.
