wehub-resource-sync
190 lines
5.2 KiB
Markdown
190 lines
5.2 KiB
Markdown
# Release Process
|
|
|
|
This document outlines the release processes for the Composio SDK. We support both automated releases through GitHub Actions and manual releases when needed.
|
|
|
|
## CLI Binary Release Process
|
|
|
|
The CLI binary release process is separate from npm publishing.
|
|
|
|
- `@composio/cli` is marked private and is not published to npm via Changesets.
|
|
- CLI binaries are built and published as GitHub Release assets by `.github/workflows/build-cli-binaries.yml`.
|
|
- Install and upgrade flows (`install.sh` and `composio upgrade`) download binaries from GitHub Releases.
|
|
- `composio upgrade --beta` resolves the newest CLI prerelease from GitHub Releases.
|
|
|
|
### Triggers
|
|
|
|
The CLI binary workflow supports two entry points:
|
|
|
|
- Beta release: the auto-generated Changesets release PR titled `Release: update version`
|
|
- Stable release: manual `workflow_dispatch`, but only from an existing beta release tag
|
|
|
|
### Beta CLI Release
|
|
|
|
When the Changesets release PR is opened or updated, the workflow:
|
|
|
|
1. Reads the bumped CLI version from `ts/packages/cli/package.json`
|
|
2. Publishes a prerelease tag in the form `@composio/cli@<version>-beta.<pr-number>`
|
|
3. Attaches the built binaries to that prerelease
|
|
|
|
### Stable CLI Release
|
|
|
|
When running **Build CLI Binaries** manually:
|
|
|
|
1. Enter an existing beta tag (for example `@composio/cli@1.2.3-beta.456`)
|
|
2. The workflow verifies that the beta release already exists and is marked as a prerelease
|
|
3. The workflow checks out the exact commit associated with that beta release
|
|
4. The workflow rebuilds the binaries and publishes the stable release under `@composio/cli@<version>`
|
|
|
|
### What the workflow does
|
|
|
|
1. Builds CLI binaries for Linux/macOS (x64 + arm64)
|
|
2. Creates platform zip archives (`composio-<platform>.zip`)
|
|
3. Publishes assets to the beta or stable GitHub Release
|
|
4. Runs `.github/workflows/cli.test-installation.yml` to validate installation paths and shell integration
|
|
|
|
### Notes
|
|
|
|
- Stable promotion is intentionally gated on an existing beta release so the shipped stable binaries always correspond to a tested beta artifact.
|
|
|
|
## Automated Release Process
|
|
|
|
The automated release process is triggered when code is merged into the `main` branch or manually through GitHub Actions.
|
|
|
|
### Requirements
|
|
|
|
- `NPM_TOKEN` secret must be configured in GitHub repository settings
|
|
- `CI_BOT_TOKEN` secret for GitHub authentication
|
|
- All changes must be documented using Changesets
|
|
- All quality checks must pass
|
|
|
|
### Using Automated Release
|
|
|
|
1. **For Regular Releases (via main branch)**
|
|
- Make sure your changeset is added to the PR you are merging to main. Run `pnpm changeset` on your branch before submiting the PR
|
|
- Get your PR merged to main
|
|
- The workflow will automatically:
|
|
- Create a release PR
|
|
- Publish packages when the release PR is merged
|
|
|
|
2. **For Manual Triggers**
|
|
- Go to GitHub Actions
|
|
- Select "TS SDK Release" workflow
|
|
- Click "Run workflow" on main branch
|
|
- Monitor the workflow progress
|
|
|
|
## Manual Release Process
|
|
|
|
The manual release process is available for cases where direct control over the release process is needed.
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js, Bun, Python, Deno, uv, and pnpm from `mise.toml`
|
|
- Access to npm registry
|
|
- Write access to the repository
|
|
|
|
### Steps
|
|
|
|
1. **Prepare for Release**
|
|
|
|
```bash
|
|
# Ensure you're on the latest main
|
|
git checkout main
|
|
git pull origin main
|
|
|
|
# Install dependencies
|
|
mise install
|
|
pnpm install
|
|
|
|
# Run quality checks
|
|
pnpm build
|
|
pnpm check:peer-deps
|
|
```
|
|
|
|
2. **Create Changeset**
|
|
|
|
```bash
|
|
pnpm changeset
|
|
```
|
|
|
|
- Select affected packages
|
|
- Choose version bump type (major/minor/patch)
|
|
- Write a detailed change description
|
|
- Commit the generated changeset file
|
|
|
|
For pre-releases:
|
|
|
|
```bash
|
|
pnpm changeset:pre-enter
|
|
pnpm changeset
|
|
```
|
|
|
|
3. **Version Packages**
|
|
|
|
```bash
|
|
pnpm changeset:version
|
|
```
|
|
|
|
- Review the version changes
|
|
- Commit the package bumps
|
|
|
|
4. **Publish Packages**
|
|
|
|
```bash
|
|
# Ensure you're logged in to npm
|
|
npm login
|
|
|
|
# Publish
|
|
pnpm changeset:release
|
|
```
|
|
|
|
### Troubleshooting
|
|
|
|
1. **Authentication Issues**
|
|
- Ensure you're logged in to npm (`npm login`)
|
|
- Check npm token validity
|
|
- Verify registry settings in `.npmrc`
|
|
|
|
2. **Build Failures**
|
|
- Clear node_modules: `pnpm clean`
|
|
- Reinstall dependencies: `pnpm install`
|
|
- Check for peer dependency issues
|
|
|
|
3. **Version Conflicts**
|
|
- Check package.json versions
|
|
- Verify changeset entries
|
|
- Review git tags
|
|
|
|
## Best Practices
|
|
|
|
1. **Changesets**
|
|
- Write clear, descriptive changeset messages
|
|
- Include breaking changes prominently
|
|
- Reference relevant issues/PRs
|
|
|
|
2. **Version Management**
|
|
- Follow semver strictly
|
|
- Document breaking changes
|
|
- Update peer dependencies appropriately
|
|
|
|
3. **Quality Assurance**
|
|
- Run all tests before release
|
|
- Check bundle sizes
|
|
- Verify documentation updates
|
|
|
|
## Post-Release
|
|
|
|
1. **Verification**
|
|
- Check npm registry for new versions
|
|
- Verify package installations
|
|
- Test example projects
|
|
|
|
2. **Documentation**
|
|
- Update changelog if needed
|
|
- Update version numbers in docs
|
|
- Announce breaking changes
|
|
|
|
3. **Cleanup**
|
|
- Remove pre-release branches if any
|
|
- Update release tickets/issues
|
|
- Archive release artifacts
|