229 lines
4.5 KiB
Markdown
229 lines
4.5 KiB
Markdown
# Funplay Cocos MCP Release Workflow
|
|
|
|
This document records the release workflow for publishing Funplay MCP for Cocos to:
|
|
|
|
- Git tags
|
|
- GitHub Releases
|
|
- Downloadable Cocos Creator extension zip packages
|
|
|
|
## Published Identity
|
|
|
|
- GitHub repository: `https://github.com/FunplayAI/funplay-cocos-mcp`
|
|
- Git tag format: `v<version>`
|
|
- GitHub Release tag: `v<version>`
|
|
- Extension package asset: `Funplay.CocosMcp.v<version>.zip`
|
|
- Cocos extension folder name inside the zip: `funplay-cocos-mcp`
|
|
- Default local MCP endpoint: `http://127.0.0.1:8765/`
|
|
|
|
## Version Alignment Rule
|
|
|
|
Keep these versions aligned:
|
|
|
|
- `package.json` `version`
|
|
- `CHANGELOG.md` release section
|
|
- Git tag `v<version>`
|
|
- GitHub Release `v<version>`
|
|
- `releases/<version>/release-manifest.json` `version`
|
|
- Release zip filename `Funplay.CocosMcp.v<version>.zip`
|
|
|
|
Example:
|
|
|
|
- `package.json`: `0.3.1`
|
|
- Git tag: `v0.3.1`
|
|
- GitHub Release: `v0.3.1`
|
|
- Release asset: `Funplay.CocosMcp.v0.3.1.zip`
|
|
|
|
## Files To Update For A New Release
|
|
|
|
Update:
|
|
|
|
1. `package.json`
|
|
- `"version": "<version>"`
|
|
2. `CHANGELOG.md`
|
|
- add a dated release notes block
|
|
|
|
Optional but recommended:
|
|
|
|
3. `README.md`
|
|
4. `README_CN.md`
|
|
5. GitHub Release notes text
|
|
|
|
## Release Steps
|
|
|
|
### 1. Verify Working Tree
|
|
|
|
```bash
|
|
git status --short --branch
|
|
```
|
|
|
|
The tree should contain only intentional release changes.
|
|
|
|
### 2. Update Versions And Notes
|
|
|
|
Update `package.json` and `CHANGELOG.md`.
|
|
|
|
Use semantic versions such as `0.3.1`, and keep release headings in this format:
|
|
|
|
```markdown
|
|
## [0.3.1] - 2026-05-20
|
|
```
|
|
|
|
### 3. Run Release Verification
|
|
|
|
```bash
|
|
npm run release:verify
|
|
```
|
|
|
|
This runs:
|
|
|
|
- JavaScript syntax checks
|
|
- Node.js tests
|
|
- release metadata validation
|
|
- release package generation
|
|
|
|
The generated local artifacts are written to:
|
|
|
|
```text
|
|
releases/<version>/
|
|
```
|
|
|
|
Expected contents:
|
|
|
|
- `Funplay.CocosMcp.v<version>.zip`
|
|
- `release-manifest.json`
|
|
- `SHA256SUMS.txt`
|
|
- `README.md`
|
|
|
|
### 4. Inspect The Package
|
|
|
|
The release script validates that every archive path stays under:
|
|
|
|
```text
|
|
funplay-cocos-mcp/
|
|
```
|
|
|
|
The package must not contain local/build content such as:
|
|
|
|
- `.git/`
|
|
- `.github/`
|
|
- `.DS_Store`
|
|
- `node_modules/`
|
|
- `Library/`
|
|
- `Temp/`
|
|
- `dist/`
|
|
- `build/`
|
|
- `test/`
|
|
- `scripts/`
|
|
|
|
Verify checksums:
|
|
|
|
```bash
|
|
cd releases/<version>
|
|
shasum -a 256 -c SHA256SUMS.txt
|
|
```
|
|
|
|
### 5. Commit, Tag, And Push
|
|
|
|
```bash
|
|
git add .
|
|
git commit -m "Release v<version>"
|
|
git tag v<version>
|
|
git push origin main
|
|
git push origin v<version>
|
|
```
|
|
|
|
### 6. Create GitHub Release
|
|
|
|
Regenerate the final release artifacts from the tagged clean commit:
|
|
|
|
```bash
|
|
npm run release:package -- --strict-tag
|
|
```
|
|
|
|
If creating a new release:
|
|
|
|
```bash
|
|
gh release create v<version> \
|
|
-R FunplayAI/funplay-cocos-mcp \
|
|
--title "v<version>" \
|
|
--notes-file /path/to/release-notes.md \
|
|
releases/<version>/Funplay.CocosMcp.v<version>.zip \
|
|
releases/<version>/release-manifest.json \
|
|
releases/<version>/SHA256SUMS.txt \
|
|
releases/<version>/README.md
|
|
```
|
|
|
|
If the release already exists and only assets need to be replaced:
|
|
|
|
```bash
|
|
gh release upload v<version> \
|
|
-R FunplayAI/funplay-cocos-mcp \
|
|
--clobber \
|
|
releases/<version>/Funplay.CocosMcp.v<version>.zip \
|
|
releases/<version>/release-manifest.json \
|
|
releases/<version>/SHA256SUMS.txt \
|
|
releases/<version>/README.md
|
|
```
|
|
|
|
### 7. Verify GitHub Release
|
|
|
|
```bash
|
|
gh release view v<version> \
|
|
-R FunplayAI/funplay-cocos-mcp \
|
|
--json url,assets,isDraft,isPrerelease,publishedAt
|
|
```
|
|
|
|
Confirm the release has all four assets.
|
|
|
|
### 8. Post-Release Smoke Test
|
|
|
|
Test the package from the public GitHub Release:
|
|
|
|
1. Download `Funplay.CocosMcp.v<version>.zip`.
|
|
2. Unzip it.
|
|
3. Move `funplay-cocos-mcp` into a Cocos project `extensions/` directory.
|
|
4. Restart Cocos Creator or reload extensions.
|
|
5. Open `Funplay > MCP Server`.
|
|
6. Start the MCP server.
|
|
7. Connect an MCP client and call `get_project_info`.
|
|
|
|
## Current Verification Commands
|
|
|
|
```bash
|
|
npm run release:verify
|
|
gh release view v<version> -R FunplayAI/funplay-cocos-mcp --json url,assets
|
|
```
|
|
|
|
## Common Failure Cases
|
|
|
|
### Release validation says the changelog section is missing
|
|
|
|
Cause:
|
|
|
|
- `CHANGELOG.md` does not contain `## [<version>] - YYYY-MM-DD`.
|
|
|
|
Fix:
|
|
|
|
- Add a dated release section before packaging.
|
|
|
|
### `zip` command is missing
|
|
|
|
Cause:
|
|
|
|
- The local environment does not have the `zip` CLI installed.
|
|
|
|
Fix:
|
|
|
|
- Install `zip`, then rerun `npm run release:package`.
|
|
|
|
### GitHub Release upload replaces the wrong assets
|
|
|
|
Cause:
|
|
|
|
- The version directory or release tag does not match `package.json` version.
|
|
|
|
Fix:
|
|
|
|
- Rerun `npm run release:check`.
|
|
- Confirm the command uses `releases/<version>/` and `v<version>`.
|