| name | frontend-miniprogram-release |
| description | Use when releasing a WeChat mini-program from a monorepo, especially when creating release PRs, bumping versions, updating CHANGELOGs, or creating version tags |
Frontend Mini-Program Release
Overview
Releasing a mini-program frontend in a monorepo requires careful scope isolation and PR-based workflows. One wrong direct-push to main can require force-push gymnastics.
When to Use
- Bumping version in
package.json for a mini-program
- Creating a release commit with version + CHANGELOG updates
- Preparing a mini-program for upload to WeChat platform
- Working in a monorepo where multiple frontends share a single git repository
Core Rules
1. Scope Isolation (CRITICAL)
Always confirm which directory the user wants to release.
git diff main..HEAD --stat
git diff main..HEAD -- wechat/
- If the release branch contains changes outside the target directory, cherry-pick or checkout only the target directory into a fresh branch from main
- Never assume "the current branch" equals "only the changes the user cares about"
2. Never Direct-Push to Protected Branches
Version bumps and release commits must go through PR, just like feature code.
git commit -m "release: v1.x.x"
git push origin main
git checkout -b release/wechat-v1.x.x
git commit -m "release(wechat): v1.x.x"
git push -u origin release/wechat-v1.x.x
- Even if you have force-push permissions, don't use them for release commits
- If you accidentally pushed to main, use
git revert + PR instead of force-push to bypass branch protection
3. CHANGELOG Format
Follow Keep a Changelog (Chinese version supported):
# Changelog
本文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范。
## [1.14.0] - YYYY-MM-DD
### Added
- New feature description (#101)
### Fixed
- Bug fix related to the new feature (#102)
## [1.13.1] - YYYY-MM-DD
### Fixed
- Bug fix description (#99)
### Changed
- Refactor or directory migration (#98)
## [1.13.0] - YYYY-MM-DD
- Use
[SemVer] version numbers with brackets
- Use
### Added / Changed / Fixed / Removed categories
- Include PR numbers where applicable:
(#101)
- Always add the new version section at the TOP of the file
- When a release contains multiple commit types, list each under its own category
4. Version Number Analysis
Before bumping, determine the new version by analyzing the actual diff, not just commit messages:
git log <last-tag>..HEAD --oneline -- <target-dir>/
git show --stat <commit> -- <target-dir>/
git diff <last-tag>..HEAD -- <target-dir>/
Commit messages are a hint, diff is the truth. A fix: commit might only touch a comment (no version bump needed), while a chore: commit might add a new page (MINOR bump).
Apply SemVer based on behavioral impact:
| What Changed | Version Bump | Example |
|---|
| New user-facing feature / new page / new API | MINOR | 1.13.0 → 1.14.0 |
| Bug fix with behavior change | PATCH | 1.13.0 → 1.13.1 |
| Pure refactor / comment update / no behavior change | No bump or bundle with other changes | Skip if nothing user-visible changed |
| Breaking change (removed API, changed response format) | MAJOR | 1.13.0 → 2.0.0 |
Decision flow:
- Does any commit add new user-visible functionality? → MINOR
- Does any commit fix a bug that users experienced? → PATCH (if no MINOR)
- Are all changes internal refactors / cleanups? → PATCH if bundling, otherwise consider skipping release
- Does any commit break backward compatibility? → MAJOR
5. Version Bump Checklist
Before creating the release PR:
Common Mistakes
| Mistake | Why It Happens | Fix |
|---|
| Direct-pushing release to main | "It's just a version bump" | Treat version bumps like any other code change |
| Including unrelated directory changes | Assuming branch only has relevant changes | Explicitly filter by target directory |
| Force-pushing after accidental push | Trying to "clean up" history | Use git revert + PR instead |
| Wrong CHANGELOG format | Copying old inconsistent format | Use Keep a Changelog standard |
| Auto-merging PR without user consent | Assuming release PRs are safe to auto-merge | Always wait for explicit user confirmation before merging |
| Bumping version based only on commit messages | fix: might be a comment edit; chore: might add a new page | Always inspect git show --stat and git diff to determine actual behavioral impact |
Leaving TODO items as in_progress while waiting | System continuously prompts for continuation | Mark blocking/waiting tasks as completed with a note, or the system will nag |
Release Flow
User: "Release wechat"
|
v
Check git diff main..HEAD -- wechat/
|
v
Analyze commits → determine SemVer bump (patch/minor/major)
|
v
Create release branch from main
|
v
Bump version + update CHANGELOG
|
v
Commit and push release branch
|
v
Create PR
|
v
Merge PR (by user or with explicit permission)
|
v
Pull latest main and create tag: wechat-miniprogram-yansongda/v1.x.x
|
v
Push tag to origin
|
v
Inform user to upload via WeChat DevTools
Tag Creation
After the release PR is merged, create a version tag:
git checkout main && git pull origin main
git tag wechat-miniprogram-yansongda/v1.x.x
git push origin wechat-miniprogram-yansongda/v1.x.x
- Tag format:
wechat-miniprogram-yansongda/v{semver}
- Always pull latest main before tagging to ensure tag points to the merged release commit
- Push tag immediately after creation
- If
git pull is not a fast-forward, resolve conflicts first (rare for release branches)
Platform Upload (Manual Step)
After PR is merged and tag is pushed, the user must manually:
- Open WeChat DevTools
- Compile and verify
- Click Upload (or 工具 → 上传)
- Enter version number and notes
- Submit for review on the platform admin page
Do not attempt automated upload — platform authentication requires manual login.
