release-and-changeset-best-practices

release-and-changeset-best-practices

Purpose

Unify pnpm change intent, commits, version coordination, and repoctl pre-release checks to avoid missing user-visible changes and scaffolding coordination.

When to use

• The user asks "does this change need a change intent / changeset?"
• The user wants to add .changeset/*.md。
• The user is preparing to release.
• The user changed weapp-vite / wevu / @weapp-vite/react / mpcore / templates/* / skills/* / dist/docs / AGENTS.md / website。
• The user changed the AI usage path, such as screenshot / compare / MCP / logs / skills installation.
• The user requests fixing a GitHub issue according to the repository process, including worktree, minimal reproduction, PR, Chinese change description, and CI wrap-up.

Inapplicable scenarios

This skill focuses on the repository delivery process, including repoctl release determination, pnpm change-intent governance, and the issue fix loop.

• Documentation sync: use docs-and-website-sync。
• Build or runtime design: use the corresponding best-practices skill.

Core process

1. First determine whether the change is user-visible; source bug fixes, new features, behavior changes, and template behavior changes should by default be handled through pnpm change add a change intent.
2. Do not easily classify the following changes as "purely internal maintenance":
   • skills/*
   • dist/docs
   • Scaffolding generation AGENTS.md
   • AI skills installation behavior
   • prepare / mcp init|print|doctor / forwardConsole
   • wv screenshot / wv compare / wv ide logs
   • web runtime / lib mode
   • React runtime, React templates, mpcore provider parity, and multi-platform build contracts
3. If the release involves weapp-vite、wevu or templates/*, by default coordinate and add create-weapp-vite bump。
4. .changeset/*.md is the pnpm change-intent storage format and does not mean using the Changesets CLI; write the summary in Chinese, describe the user-perceived result, and do not write it as an internal refactoring ledger.
5. If the task comes from a GitHub issue:
   • First create in a writable directory of the repository git worktree
   • Prefer e2e-apps/github-issues or a minimal entry point for a stable reproduction
   • First add root-cause-related unit / e2e tests, then wrap up the PR
6. Delivery follows Conventional Commits; by default commit-only, issue fixes go through the PR process.
   • For platform-sensitive changes, first locate the earliest OS divergence, and check command launch, path normalization, line endings, and filesystem assumptions.
   • For touched DevTools parity scenarios, also verify mpcore unit/integration, browser e2e, and necessary type tests.
7. Before release, prefer running repository scripts:
   • pnpm change status
   • node --import tsx scripts/check-create-weapp-vite-changeset.ts
   • node --import tsx scripts/check-catalog-changeset.ts
   • stable：repo release stable prepare / repo release stable publish
   • prerelease：repo release pre enter <alpha|beta|rc|next> / repo release pre publish / repo release pre exit
   • Restore single-package release:repo release ci --mode publish-unpublished --package <name> --version <version>

Skills change determination

• Changes to skill body text, trigger metadata, scaffolding AGENTS, or website AI routing are user-visible AI workflow changes and should not be handled as pure comment maintenance.
• As long as the change affects the default guidance generated by create-weapp-vite , by default also check create-weapp-vite bump and template output regression.
• The change-intent summary describes the AI workflow, verification path, or command routing changes the user gains, and does not list internal copy rearrangements.

Constraints

• Do not miss the pnpm change intent for source bug fixes.
• Do not forget create-weapp-vite coordination.
• Do not write English or vague summaries.
• Do not misjudge user-visible AI / docs / template contracts as purely internal changes.
• Do not directly modify source code and open a PR when the reproduction is unstable.
• Do not treat a failure that occurs only on a certain OS, DevTools login, port, or automator connection as a product behavior regression.

Output

When applying this skill, the output must include:

• Whether a pnpm change intent is needed and the reason.
• Whether create-weapp-vite coordination is needed.
• Recommended commit type.
• Recommended check commands.
• If it comes from an issue, supplement the reproduction path and PR delivery status.

Completion markers

• The change-intent requirement has been clearly determined.
• A Chinese change intent has been added when needed.
• Added when needed create-weapp-vite bump。
• The commit method and delivery method comply with repository rules.
• When fixing an issue, the worktree, reproduction, regression, and PR loop have been completed.

Reference materials

• references/release-checklist.md
• references/issue-fix-checklist.md