64898b2c79
1.5 KiB
paths
| paths | ||
|---|---|---|
|
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.