This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch release_0.17.0 in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 9c02a59a9d23ae68d90ec9f0e645fcb31e663eff Author: 慕白 <[email protected]> AuthorDate: Sun Apr 19 22:54:04 2026 +0800 Add release-major-version skill --- .claude/skills/release-major-version/SKILL.md | 258 ++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) diff --git a/.claude/skills/release-major-version/SKILL.md b/.claude/skills/release-major-version/SKILL.md new file mode 100644 index 000000000..9b0f50164 --- /dev/null +++ b/.claude/skills/release-major-version/SKILL.md @@ -0,0 +1,258 @@ +--- +name: release-major-version +description: >- + Prepare the Apache Fory site for a new major-ish docs release such as 0.17: + write the release blog, checkpoint with git commits, translate the zh-CN + release blog and docs, create the versioned docs snapshot, update the + default docs version, and run an independent self-review to catch remaining + issues. Use when the user asks to cut a new docs/site release version on + this repository. +--- + +# Release Big Version + +Use this skill for the `apache/fory-site` repository when preparing a new docs/site release such as `0.17`. + +This skill is for the website/docs repository workflow, not the ASF source release/signing workflow in `docs/community/how_to_release.md`. + +## Scope + +This workflow covers: + +1. Write the release blog post +2. Git commit the blog/content checkpoint +3. Translate the zh-CN release blog and zh-CN docs +4. Git commit the translation checkpoint +5. Version the docs with `yarn docusaurus docs:version <version>` +6. Update the default docs version to the new version +7. Run a fresh subagent review before calling the work done + +## Repository Facts You Must Respect + +- Current docs live in `docs/` +- Versioned English docs live in `versioned_docs/version-<ver>/` +- Versioned sidebars live in `versioned_sidebars/version-<ver>-sidebars.json` +- Chinese docs live in `i18n/zh-CN/docusaurus-plugin-content-docs/current/` +- Versioned Chinese docs live in `i18n/zh-CN/docusaurus-plugin-content-docs/version-<ver>/` +- Chinese blog posts live in `i18n/zh-CN/docusaurus-plugin-content-blog/` +- Docs version history is recorded in `versions.json` +- The default released docs version is controlled by `docs.lastVersion` in `docusaurus.config.ts` +- The wrapped versioning command is `yarn docusaurus docs:version <ver>`, which calls `scripts/docusaurus-with-i18n.sh` +- The wrapper copies every locale's `current/` docs tree to `version-<ver>/` after Docusaurus versions the English docs + +## Important Caveats + +- Do not run raw `docusaurus docs:version <ver>` directly. Use `yarn docusaurus docs:version <ver>` so zh-CN docs are copied too. +- Do not version docs before the English docs and zh-CN docs are in the state you want to freeze for that release. +- Run `npm run copy-i18n-fallback` before cutting the version if zh-CN `benchmarks/` or `specification/` content may still rely on fallback copies. +- `copy-i18n-fallback.sh` can create untracked fallback files under `i18n/zh-CN/.../benchmarks` and `.../specification`; do not confuse those with intentional edits. +- This repo already has some broken zh-CN doc links. A full build can fail for pre-existing reasons unrelated to your release changes. Distinguish new regressions from known baseline issues. +- Keep `tasks/*.md` and `tasks/lessons.md` out of git. +- `docs/guide` and `docs/specification` are mainly synced from `apache/fory`; avoid site-only divergence there unless that upstream sync is intentionally part of the release work. +- Abort early if target-version artifacts already exist unless the user explicitly wants to resume/repair a partial release cut. This includes: + - `blog/*fory_<version>_release.md` + - `static/img/blog/fory_<version>_release/` + - `versioned_docs/version-<version>/` + - `versioned_sidebars/version-<version>-sidebars.json` + - `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/` + +## Step 0: Prepare Context + +1. Read: + - `package.json` + - `docusaurus.config.ts` + - `versions.json` + - `scripts/docusaurus-with-i18n.sh` +2. Confirm the current latest released version, the target new version, and the previous released version that will become the explicit older-version route after the cut. +3. Verify the site repo already contains the intended upstream docs state from `apache/fory` before you start. At minimum: + - check whether the needed `docs/guide` and `docs/specification` changes are already present in this repo + - if not, stop and sync or ask the user before freezing a stale snapshot +4. Check that the target version is clean: + - the release blog filename does not already exist unless this is an intentional continuation + - the blog asset directory does not already exist unless this is an intentional continuation + - `versioned_docs/version-<version>/` does not already exist + - `versioned_sidebars/version-<version>-sidebars.json` does not already exist + - `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/` does not already exist +5. Scan: + - `blog/` for the previous release post to use as template + - `docs/`, `versioned_docs/`, and `i18n/zh-CN/docusaurus-plugin-content-docs/` so you understand the current tree +6. If the task is non-trivial, maintain a task note under `tasks/task-<slug>.md` and archive it to `tasks/history/` when finished. + +## Step 1: Write the Release Blog + +1. Find the previous release blog in `blog/`, typically `blog/YYYY-MM-DD-fory_<prev>_release.md`. +2. Create the new release post by adapting the previous one instead of starting from scratch. +3. Update the post carefully: + - frontmatter `slug`, `title`, `tags`, date-based filename + - opening release paragraph + - compare link + - PR counts / contributor counts if the post includes them + - highlights/features/fixes sections + - benchmark images and asset paths +4. Put blog-specific assets under `static/img/blog/fory_<version>_release/` when the post needs dedicated images. +5. If you add benchmark images, ensure the referenced static paths and copied files match exactly. +6. Validate the post for obvious copy/paste errors from the previous release. + +## Step 1A: Bump Versioned References in Current Docs + +Before translating the zh-CN blog/docs or freezing the docs version, update all pinned current-doc references to the new release version. + +Required targets: + +1. `docs/start/install.md` +2. `docs/guide/**/index.md` for each language/runtime that includes versioned install or dependency examples +3. other current guide pages with pinned version examples, dependency strings, or install snippets +4. any other current docs page that still advertises the previous release as the recommended install version + +Minimum workflow: + +1. Replace the previous release version with the new release version in `docs/start/install.md` +2. Scan all current docs for pinned release strings and update them where they describe the latest recommended version +3. Explicitly inspect `docs/guide/**/index.md` because these pages often carry language-specific install snippets and versioned dependency examples +4. Update every latest-version reference before `yarn docusaurus docs:version <version>` so the frozen snapshot inherits the correct release version +5. Be especially suspicious of: + - Maven/Gradle coordinates + - `pip install`, `go get`, `cargo add`, `dotnet add package` + - Bazel dependency examples + - language-guide install snippets under `docs/guide/**` + - language `index.md` pages under `docs/guide/**/index.md` +6. Finish all of these English/current-doc version updates before starting zh-CN translation, so the Chinese docs/blog are translated once from the final English source rather than patched twice +7. Do this before `yarn docusaurus docs:version <version>` so the released snapshot freezes the correct install guidance + +## Step 2: Git Commit the Blog Checkpoint + +1. Review the diff for the new blog post and any new assets. +2. Make a focused git commit for the blog/release-post changes. +3. Do not bundle unrelated generated files into this commit. + +## Step 3: Translate zh-CN Docs + +1. Use the Chinese translation workflow skill: + - Prefer repo-local `.agents/skills/translate-docs-zh/SKILL.md` if it exists + - Otherwise use `.claude/skills/translate-docs-zh/SKILL.md` +2. Start this step only after the English release blog and all current-doc version bumps are final. +3. Translate or sync the zh-CN release blog: + - source: `blog/<release-file>.md` + - target: `i18n/zh-CN/docusaurus-plugin-content-blog/<release-file>.md` + - preserve frontmatter structure and blog metadata unless a localized change is needed + - keep blog asset paths aligned with the English source unless there is a deliberate zh-only asset change +4. Translate or sync the zh-CN docs for the doc changes that should ship with the new release. + - primary path mapping: `docs/<subpath>` -> `i18n/zh-CN/docusaurus-plugin-content-docs/current/<subpath>` +5. Follow the translation skill's hard rule: no external translation tools or services. +6. If top-level category labels changed, also update: + - `i18n/zh-CN/docusaurus-plugin-content-docs/current.json` +7. If the release needs localized version metadata, plan a manual follow-up for `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>.json`; the versioning wrapper does not create it. + +## Step 4: Git Commit the zh-CN Checkpoint + +1. Review only the intended zh-CN docs changes. +2. Include both the zh-CN release blog and zh-CN docs translation/sync in this checkpoint. +3. Commit the Chinese translation/sync separately from the release blog commit. +4. Leave task notes and lessons unstaged. + +## Step 5: Freeze the New Docs Version + +Before freezing: + +```bash +npm run copy-i18n-fallback +``` + +Then, after English and zh-CN current docs are ready, run: + +```bash +yarn docusaurus docs:version <version> +``` + +Expected effects: + +- Docusaurus snapshots English docs into `versioned_docs/version-<version>/` +- Docusaurus creates `versioned_sidebars/version-<version>-sidebars.json` +- The wrapper script copies zh-CN current docs into `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/` +- `versions.json` is updated + +After the command: + +1. Inspect the new `versioned_docs/version-<version>/` tree +2. Inspect `versioned_sidebars/version-<version>-sidebars.json` +3. Inspect `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>/` +4. Check for accidental carry-over of placeholder or half-English zh-CN content before accepting the snapshot +5. Decide whether a manual `i18n/zh-CN/docusaurus-plugin-content-docs/version-<version>.json` should be added for this release +6. If a later validation/build step generates additional fallback files under the new `version-<version>/` zh-CN tree, inspect them explicitly and decide whether they belong in the release commit + +## Step 6: Update the Default Docs Version + +1. Edit `docusaurus.config.ts` +2. Change: + +```ts +docs: { + lastVersion: '<version>', +} +``` + +3. Keep the existing repo style for `docs.versions` entries unless there is a concrete reason to change it +4. Verify `versions.json` now lists the new version first + +## Step 7: Validate + +Minimum validation: + +1. `npm run typecheck` +2. `npm run build` +3. Review the output and separate: + - new failures caused by your changes + - pre-existing failures, especially zh-CN broken links + +Recommended route checks when the build is usable: + +- `/` +- `/docs` +- `/zh-CN/docs` +- `/docs/<previous-version>/` +- `/zh-CN/docs/<previous-version>/` +- `/blog` +- `/zh-CN/blog` + +Also run targeted checks: + +- parameterize stale-version scans using the actual old/new versions instead of hard-coded values +- scan at least: `blog`, `docs`, `versioned_docs/version-<version>`, and `i18n/zh-CN/docusaurus-plugin-content-docs` +- for example, search for the previous release string, older release strings likely to be copy/paste remnants, and placeholders such as `TODO` / `TBD` +- treat stale latest-version references in current install/docs pages as blocking, especially in `docs/start/install.md`, `docs/guide/**/index.md`, and other `docs/guide/**` pages +- confirm release blog asset paths exist under `static/img/blog/fory_<version>_release/` + +## Step 8: Fresh Self-Review + +Before marking the task complete, spawn a fresh subagent and ask it to review the work with no answer leakage. + +The review should check at least: + +1. Are there still stale version strings or previous-release copy/paste remnants? +2. Did versioning update the expected files only? +3. Are zh-CN docs/versioned docs consistent with the intended snapshot? +4. Are the zh-CN release blog and English release blog both present and consistent with the intended release state? +5. Are blog asset paths and benchmark links valid? +6. Are there any obvious missing follow-up edits, such as `docs/start/install.md` or guide pages with pinned version references that should move to the new release? +7. Did the workflow accidentally snapshot stale site docs because upstream `apache/fory` doc changes were not synced first? + +Treat review findings as blocking until resolved or explicitly documented. + +## Commit Strategy + +Preferred checkpoints: + +1. Blog/release-post commit +2. zh-CN release blog + docs translation commit +3. versioning/default-version commit + +Keep commits focused so rollback and review stay simple. + +## Output Requirements + +When reporting completion, include: + +1. What changed +2. Which commits or commit boundaries were created +3. Validation results +4. Any remaining known issues or pre-existing build failures --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
