Commits and public releases

Commit and PR subjects

Use type(scope): specific change, with an imperative verb and a subject of at most 100 characters. Keep each commit focused on one coherent task. Use the body for the reason, relevant tradeoffs, and validation; never include secrets. PR titles follow the same convention because squash merges use them as subjects.

Write fix(tiktok): preserve both follower pagination values, for example. Avoid vague subjects such as fix(api): fix issue, conversational claims such as “finally works,” and private provider names or infrastructure addresses. Describe the behavior the code changes. Mark incompatible changes with ! and explain the required migration in the body.

The commit hook runs commitlint. Its shared policy rejects known private provider names, addresses, credential values, and vague subjects. These checks catch known mistakes; they cannot decide whether arbitrary prose is appropriate to publish.

Public API changelog

The source is release-notes.json. Each batch names a full mainCommit SHA and a changes array containing category and summary. Categories are Added, Improved, Fixed, Changed, and Removed. Summaries are single-line customer-facing text, at most 700 characters.

Group related commits into one entry describing the resulting feature or fix. A release may contain several unrelated entries. Do not reproduce commit logs, PR numbers, debugging narratives, vendor relationships, architecture, or deployment details. Retain compatibility changes and concrete migration steps. Internal maintenance usually needs no public entry. Read the public-copy skill when writing release summaries.

Prepare draft wording in the PR description while a change is on beta. After promotion to main, confirm the production rollout succeeded, then add the reviewed batch to release-notes.json using the promotion commit's full SHA. The generator verifies main ancestry, not deployment health. Do not announce a failed or pending rollout as shipped. Use one note update for the release batch.

git fetch origin main:refs/remotes/origin/main
git log origin/main --first-parent -5 --format='%H %s'
# Edit release-notes.json with the reviewed batch and its main commit.
pnpm changelog:api
pnpm changelog:api --check

The generator accepts only first-parent commits on origin/main after its privacy floor and groups notes by the commit's UTC date. It never reads commit messages for public text or falls back to beta/HEAD. A checkout without the required history fails closed. For a shallow clone, fetch with --unshallow before running the commands above. Regeneration is automatic during docs builds; writing and reviewing the release summaries is deliberate.

Review and commit both the source notes and generated MDX. Publish with the docs deployment procedure. Package changesets and the internal worker changelog have separate purposes; see operations.

Repairing a published entry

Correct or consolidate the source notes, regenerate, inspect the complete page, and deploy the docs again. Check the live page and the search index for the removed wording. Do not edit only the generated MDX: the next build replaces it. Do not rewrite shared Git history as a changelog repair. Removing text from our site cannot recall copies already downloaded or retained by external services.