# 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>`.