111 lines
4.5 KiB
Markdown
111 lines
4.5 KiB
Markdown
|
---
|
||
|
|
name: reno-release-notes
|
||
|
|
description: 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](https://docs.openstack.org/reno/latest/) 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):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
---
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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).
|