43d41a242eThis PR reorganizes and extends the existing documentation in preparation for publishing on https://modelcontextprotocol.io/. The current plan is for docs to remain in this repo, and be synced to the `modelcontextprotocol/modelcontextprotocol` whenever necessary (e.g., accompanying a release of the registry). I have included a script in https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1725 (`bin/pull-registry-docs.sh`) that can be run manually to perform the sync. If we later decide to permanently move the docs to the `modelcontextprotocol/modelcontextprotocol` repo, that also works. This PR puts all https://modelcontextprotocol.io/ docs into `docs/modelcontextprotocol-io/`. Docs outside that subdirectory, such as `docs/administration/admin-operations.md`, are intended to be accessible solely via this repo. One major exception is the `docs/reference/server-json/` subdirectory, which will depend on the resolution of https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649. However, I think we could address that in a follow-up PR. --------- Co-authored-by: Adam Jones <adamj+git@anthropic.com> Co-authored-by: Claude <noreply@anthropic.com>
60 lines
No EOL
2.7 KiB
Markdown
60 lines
No EOL
2.7 KiB
Markdown
# Release Guide
|
||
|
||
## Creating a Release
|
||
|
||
1. **Go to GitHub**: Navigate to https://github.com/modelcontextprotocol/registry/releases
|
||
2. **Click "Draft a new release"**
|
||
3. **Choose a tag**: Click "Choose a tag" and type a new semantic version that follows the last one available (e.g., `v1.0.0`)
|
||
5. **Generate notes**: Click "Generate release notes" to auto-populate the name and description
|
||
6. **Publish**: Click "Publish release"
|
||
|
||
The release workflow will automatically:
|
||
- Build binaries for 6 platforms (Linux, macOS, Windows × amd64, arm64)
|
||
- Create and push Docker images with `:latest` and `:X.Y.Z` tags (note: no 'v' prefix)
|
||
- Attach all artifacts to the GitHub release
|
||
- Generate checksums and signatures
|
||
|
||
## After Release
|
||
|
||
- Docker images will be available at:
|
||
- `ghcr.io/modelcontextprotocol/registry:latest` - Latest stable release
|
||
- `ghcr.io/modelcontextprotocol/registry:X.Y.Z` - Specific release version (note: no 'v' prefix)
|
||
- Binaries can be downloaded from the GitHub release page
|
||
|
||
## Deploying to Production
|
||
|
||
Releases do not automatically deploy to production. To deploy a release:
|
||
|
||
1. Update `mcp-registry:imageTag` in `deploy/Pulumi.gcpProd.yaml` to the desired version (e.g., `1.2.3` - note: no 'v' prefix)
|
||
2. Commit and push the change to the `main` branch (either through a PR or by pushing directly to main)
|
||
3. The [deploy-production.yml](../../../.github/workflows/deploy-production.yml) workflow will automatically trigger and deploy the specified version
|
||
|
||
See the [deployment documentation](../../../deploy/README.md) for more details.
|
||
|
||
## Staging
|
||
|
||
Staging auto-deploys from `main` via [deploy-staging.yml](../../../.github/workflows/deploy-staging.yml). It always runs the latest `main` branch code.
|
||
|
||
## Rollback
|
||
|
||
To rollback production, update `deploy/Pulumi.gcpProd.yaml` to the previous version and push.
|
||
|
||
**Note:** Rollbacks may not work as expected if the release included database migrations, since migrations are not automatically reversed.
|
||
|
||
## Docker Image Tags
|
||
|
||
The registry publishes different Docker image tags for different use cases:
|
||
|
||
- **`:latest`** - Latest stable release (updated only on releases)
|
||
- **`:X.Y.Z`** - Specific release versions (e.g., `:1.0.0` - note: no 'v' prefix)
|
||
- **`:main`** - Rolling tag updated on every push to main branch (continuous deployment)
|
||
- **`:main-YYYYMMDD-sha`** - Specific development builds from main branch
|
||
|
||
**Note:** Git release tags include the 'v' prefix (e.g., `v1.0.0`), but Docker image tags follow the standard Docker convention and do not include the 'v' prefix (e.g., `1.0.0`).
|
||
|
||
## Versioning
|
||
|
||
We use semantic versioning (SemVer):
|
||
- `v1.0.0` - Major release with breaking changes
|
||
- `v1.1.0` - Minor release with new features
|
||
- `v1.0.1` - Patch release with bug fixes |