Version Release

NG-ZORRO Version Release Guide

Scope

This skill is for the real release process of the NG-ZORRO/ng-zorro-antd repository. It is not a generic npm release checklist.

It covers:

1. Preparing a release branch and release PR
2. Using the agent-friendly stage-release prepare mode for local release file preparation
3. Maintaining the root changelog and both documentation changelog files
4. Publishing the npm package through the Azure release pipeline
5. Deploying the documentation site through Azure
6. Post-release follow-up such as GitHub Release, blog, and social announcements

Do not use this skill for unrelated changelog editing, normal feature PRs, or ad hoc package publishing outside the repository release process.

Key Project Facts

• The root package.json version is 0.0.0-NOT-USED; do not treat it as the release version.
• The library version lives in components/package.json.
• The Angular version token is updated in components/version/version.ts.
• The helper script is npm run stage-release, implemented by scripts/release/release.ts.
• Running npm run stage-release with no subcommand starts the original interactive human workflow.
• Agent work should use the non-interactive prepare mode: npm run stage-release -- prepare --version <version> --base <branch>.
• Prepare mode only prepares local release files. It does not build, push, publish, or deploy.
• Release PRs normally update three changelog files: CHANGELOG.md, docs/changelog.en-US.md, and docs/changelog.zh-CN.md.
• The docs changelog format is not identical to CHANGELOG.md; preserve each file's existing frontmatter, intro text, headings, and style.
• docs/changelog.zh-CN.md should be a Chinese translation of the public release notes, not a raw copy of the English text.
• Build, library publishing, and site deployment are normally performed by Azure pipelines, not by local agent execution.
• Official npm publishing is done from Azure after CI succeeds; do not default to local npm publish.

Before Acting

First inspect the repository state instead of guessing:

git status --short
git branch --show-current
git remote -v
node -v
cat components/package.json
git tag --list | grep -v -E '(experimental|alpha|resource)' | sort -V | tail -20

Confirm:

• The working tree is clean before running npm run stage-release.
• A remote pointing at NG-ZORRO/ng-zorro-antd exists; the script auto-detects it as upstream.
• The local Node version satisfies the root package.json engines.
• The next version is greater than the current components/package.json version.

If the working tree has user changes, do not overwrite or stage them unless the user explicitly asks.

Preparing a Release PR As An Agent

Use this flow when the user asks to prepare a release, create a release PR, or bump a version.

1. Use The Non-Interactive Prepare Mode

Use:

npm run stage-release -- prepare --version <version> --base <branch>

Examples:

npm run stage-release -- prepare --version 21.3.2 --base v21
npm run stage-release -- prepare --version 22.0.0 --base master

Prepare mode:

• Fetches the requested upstream base branch and tags.
• Verifies the working tree is clean before writing files.
• Verifies current HEAD is based on the requested base branch.
• Detects the previous release tag from tags merged into that base branch.
• Updates components/package.json.
• Updates components/version/version.ts.
• Runs npm run changelog.
• Prints the changelog boundary and the PR base branch to use.
• Does not run local build, push a release branch, publish npm, or deploy the site.

Use --dry-run to check the base branch and changelog boundary without writing files:

npm run stage-release -- prepare --version 21.3.2 --base v21 --dry-run

The original interactive mode is still available for human releasers:

npm run stage-release

2. Version Bump

Prepare mode updates the release version in:

• components/package.json
• components/version/version.ts

Use the version requested by the user if valid. If the user does not give a version, inspect the current version, recent tags, and pending release context before recommending one.

Allowed formats are x.y.z, x.y.z-alpha.n, x.y.z-beta.n, and x.y.z-rc.n.

Do not manually edit the root package.json release version.

3. Changelog

Prepare mode generates or refreshes changelog content by running:

npm run changelog

In this repository, changelog content is generated into CHANGELOG.md and then processed for the site. That generated output is only the starting point.

Manually update and review all three changelog files:

• CHANGELOG.md
• docs/changelog.en-US.md
• docs/changelog.zh-CN.md

Important formatting rules:

• Keep CHANGELOG.md in its existing root changelog format.
• Keep docs/changelog.en-US.md in the docs page format, including frontmatter and intro content.
• Keep docs/changelog.zh-CN.md in the Chinese docs page format, including frontmatter and intro content.
• Add the target release section near the top of each file, following the existing ## <version> and date layout in that file.
• Do not blindly paste the same Markdown block into all three files; docs changelog files have their own page structure.

Review each release entry carefully:

• Make sure the target version heading exists.
• Make sure important PRs are represented and grouped sensibly.
• Remove noise if needed.
• Keep English wording suitable for public release notes.
• Translate the Chinese changelog entries naturally in docs/changelog.zh-CN.md, preserving PR links, issue links, commit links, component scopes, and code identifiers.

Do not mark the changelog step complete until the English and Chinese release notes have both been reviewed.

4. API And Demo Version Tags

For every minor or major release, this is a required step after changelog review and before the release commit and PR. Review features introduced in the release range and add missing version tags to their existing API and demo documentation. Patch releases skip this step unless version-tag corrections are explicitly requested.

• In components/<component>/doc/index.en-US.md and index.zh-CN.md, use the API table's Version / 版本 column. Add the column when absent, leaving unrelated rows empty and preserving existing version values. Keep table cells aligned, including empty global-config cells.
• Mark a new API with its introduction version, for example 22.1.0. When only a new capability of an existing API is introduced, qualify the version: responsive object: 22.1.0 / 响应式对象：22.1.0. Do not imply the whole API is new.
• In components/<component>/demo/<demo>.md, add version: <version> to the YAML frontmatter of demos introducing or newly demonstrating the feature. This is the demo version badge; preserve the existing order, titles, bilingual descriptions, and demo source code.
• Use the actual introduction version from the release history. Preserve earlier version tags; bug fixes and unchanged APIs or demos do not receive a new feature version tag.
• Keep this step limited to version columns and demo frontmatter. Preserve descriptions, types, defaults, examples, and general guide content. Additional explanations, API rewrites, or new demos belong to a separately requested documentation change.

Complete this step when each new feature's applicable API rows and demos have been checked, the English and Chinese version labels agree, and the diff contains only the intended tags and any necessary table formatting. Features without an applicable API row or demo need no new prose.