4.5 KiB
| name | description |
|---|---|
| reno-release-notes | Create, review and lint pgLab release notes with reno (releasenotes/notes YAML fragments). Use whenever the user mentions reno, release notes, releasenotes/notes, "reno new", "reno lint", or asks to add or check a note for a user-visible change in pgLab, even if reno is not named explicitly. |
reno release notes in pgLab
pgLab uses reno for release notes.
Each user-visible change adds its own small YAML file in releasenotes/notes/,
committed together with the change. reno derives the release from git tags, so
never move or rename notes to change releases. Content is reStructuredText, not
Markdown.
The notes are rendered in the Sphinx user docs through the
.. release-notes:: directive in docs/releasenotes.rst (docs build:
pip install -r docs/requirements.txt && sphinx-build -b html docs userdocs).
The About dialog links to the generated releasenotes.html.
When to write a note
Write one for: new features, behaviour changes users will notice (UI, menus, shortcuts, query/code generation output, connection handling), bug fixes, known issues, and upgrade impact (e.g. changed stored settings or connection config format).
Skip: pure refactors, build-system/CI changes, test-only changes, internal code cleanup, docs-only edits.
Sections configured for this project
Defined in releasenotes/config.yaml (render order). Only these keys are valid;
others (deprecations, critical) are NOT configured here and will not render.
| Key | Rendered title | Use for |
|---|---|---|
prelude |
(implicit) | Release-wide summary, single string |
features |
New Features | New functionality |
other |
Changes | Changes to existing behaviour, minor items |
issues |
Known Issues | Known problems / limitations |
upgrade |
Upgrade Notes | What users must do or know when upgrading |
security |
Security Issues | Security fixes |
fixes |
Bug Fixes | Ordinary bug fixes |
Every section except prelude is a list of strings. Encoding is utf8.
Creating a note
From the repo root (pip install reno if missing):
reno new short-descriptive-slug
This creates releasenotes/notes/short-descriptive-slug-<16 hex>.yaml. Keep the
random suffix. Existing examples: f5-bindings-…,
connection-details-in-window-title-…, dollar-quoted-string-….
Delete all unused template sections, keep only what you need.
---
features:
- |
The query tool now executes the current statement with
:kbd:`F5`.
fixes:
- |
Fixed reconnect dialog that kept popping up after the connection was lost.
Short single-line items may be plain (- text), longer ones use - |.
Wrap at roughly 80 columns.
Writing style
- Write for pgLab users, not patch reviewers: describe the visible effect, not the implementation (no class or function names unless users see them).
- Past or present tense, full sentences, one bullet per distinct change.
- RST markup: inline literals with double backticks (
``pg_catalog``), links as`text <https://example.com>`_, GUI menu paths with:menuselection:(e.g.:menuselection:Help --> About``), keys with:kbd:. No Markdown, no single-backtick code. - Mention the PostgreSQL feature or object type involved when relevant.
- For
upgrade, state the action required.
Validate before committing
reno lint
reno list # note must be tracked by git to appear for tagged history
Common failures: YAML indentation/tabs, misspelled section key, a string where
a list is required (or a list for prelude), an unconfigured section, bad RST.
Optionally build the docs (command above) to check rendering.
Commit rules
git add releasenotes/notes/<file>and commit it in the same commit as the change, not a follow-up.- Commit messages are plain imperative sentences (e.g. "Fix reconnect dialog popping up repeatedly.").
- To correct a note, edit the same file; don't add a second one.
Troubleshooting
- Note missing in report: not committed, or shallow clone without tags
(
git fetch --tags --unshallow). - Wrong release: decided by git history/tags; check
reno list. - Broken rendering: almost always RST (single backticks, Markdown links, indentation).