64898b2c79
Some checks failed
Code scanning / CodeQL (push) Failing after 15s
Zulip production suite / Ubuntu 22.04 production build (push) Failing after 26s
Zulip production suite / Debian 12 production install with custom db name and user (push) Has been skipped
Zulip production suite / Ubuntu 22.04 production install and PostgreSQL upgrade with pgroonga (push) Has been skipped
Zulip production suite / Ubuntu 24.04 production install (push) Has been skipped
Zulip production suite / Ubuntu 26.04 production install (push) Has been skipped
Zulip production suite / Debian 13 production install (push) Has been skipped
Zulip production suite / 7.0 Version Upgrade (push) Has been skipped
Zulip production suite / 8.0 Version Upgrade (push) Has been skipped
Zulip production suite / 6.0 Version Upgrade (push) Has been skipped
Zulip production suite / 10.0 Version Upgrade (push) Has been skipped
Zulip production suite / 9.0 Version Upgrade (push) Has been skipped
Zulip production suite / 12.0 Version Upgrade (push) Has been skipped
Zulip production suite / 11.0 Version Upgrade (push) Has been skipped
GitHub Actions Security Analysis with zizmor / zizmor (push) Failing after 3s
Zulip CI / Debian 12 (Python 3.11, backend + documentation) (push) Failing after 26s
Zulip CI / Ubuntu 22.04 (Python 3.10, backend + frontend) (push) Failing after 3s
Zulip CI / Ubuntu 24.04 (Python 3.12, backend) (push) Failing after 25s
Zulip CI / Ubuntu 26.04 (Python 3.14, backend) (push) Failing after 25s
Zulip CI / Debian 13 (Python 3.13, backend) (push) Failing after 28s
Zulip production suite / Required jobs (push) Has been cancelled
Zulip CI / Required jobs (push) Has been cancelled
API Documentation Update Check / check-feature-level-updated (push) Has been cancelled
API Documentation Update Check / notify-if-api-docs-changed (push) Has been cancelled
33 lines
1.5 KiB
Markdown
33 lines
1.5 KiB
Markdown
---
|
|
paths:
|
|
- "zerver/openapi/**"
|
|
- "api_docs/**"
|
|
---
|
|
|
|
# Documenting API Changes
|
|
|
|
API changes must be documented fully using our double-entry changelog
|
|
system. When starting an API change, reread `docs/documentation/api.md`
|
|
to review the process for documenting an API change. Run
|
|
`tools/create-api-changelog`; it generates an empty
|
|
`api_docs/unmerged.d/ZF-XXXXXX.md` file (where `XXXXXX` is a random
|
|
hex string the tool picks for you) and stages it for you. Document
|
|
the changes in that file as an unordered list (`*` bullets) of the
|
|
additions or changes, formatted to match `api_docs/changelog.md`.
|
|
Don't add a `**Feature level**` heading; the merge tooling emits that
|
|
itself.
|
|
|
|
In the OpenAPI yaml (`zerver/openapi/zulip.yaml`), reference the same
|
|
filename stem in **Changes** notes, e.g.,
|
|
`**Changes**: New in Zulip 13.0 (feature level ZF-XXXXXX).` The merge
|
|
process matches the `Zulip <version> (feature level ZF-XXXXXX)` shape
|
|
and overwrites both the version and the placeholder with the real
|
|
release version and final feature level. Use the upcoming release's
|
|
version — the next major release after the latest one shipped (e.g.,
|
|
13.0 while 12.0 is the current release), which you can read from the
|
|
first `## Changes in Zulip X.Y` heading in `api_docs/changelog.md`.
|
|
You must keep the literal `New in Zulip X.Y` format, or the merge
|
|
tooling won't recognize the note and CI (`check-feature-level-updated`)
|
|
will fail with the `ZF-` placeholder still in the file. Never update
|
|
`API_FEATURE_LEVEL` manually.
|