|
| 1 | +# Release Process |
| 2 | + |
| 3 | +This repository uses [Changesets](https://github.com/changesets/changesets) for automated package versioning and publishing. |
| 4 | + |
| 5 | +## How It Works |
| 6 | + |
| 7 | +### 1. Creating Changes |
| 8 | +When you make changes that should trigger a release: |
| 9 | + |
| 10 | +```bash |
| 11 | +# Add a changeset describing your changes |
| 12 | +pnpm changeset |
| 13 | + |
| 14 | +# Follow the prompts to: |
| 15 | +# - Select which packages are affected |
| 16 | +# - Choose the type of change (patch, minor, major) |
| 17 | +# - Write a description of the change |
| 18 | +``` |
| 19 | + |
| 20 | +This creates a markdown file in `.changeset/` describing the change. |
| 21 | + |
| 22 | +### 2. Automated Release Process |
| 23 | + |
| 24 | +When changesets are pushed to `main`: |
| 25 | + |
| 26 | +1. **Release PR Creation**: The GitHub Action automatically creates a "Version Packages" PR |
| 27 | +2. **Review Process**: The PR shows exactly what will be released and requires review |
| 28 | +3. **Publishing**: When the PR is merged, packages are automatically published to NPM |
| 29 | +4. **GitHub Releases**: Release notes are automatically created with changelogs |
| 30 | + |
| 31 | +### 3. Manual Testing |
| 32 | + |
| 33 | +You can test releases locally: |
| 34 | + |
| 35 | +```bash |
| 36 | +# See what would be published (dry run) |
| 37 | +pnpm publish:dry-run |
| 38 | + |
| 39 | +# Build and publish locally (requires NPM_TOKEN) |
| 40 | +pnpm publish |
| 41 | +``` |
| 42 | + |
| 43 | +## Setup Requirements |
| 44 | + |
| 45 | + |
| 46 | +## Changeset Types |
| 47 | + |
| 48 | +- **patch**: Bug fixes, documentation updates, internal changes |
| 49 | +- **minor**: New features, non-breaking changes |
| 50 | +- **major**: Breaking changes, API changes |
| 51 | + |
| 52 | +## Example Workflow |
| 53 | + |
| 54 | +```bash |
| 55 | +# 1. Make your changes |
| 56 | +git checkout -b feature/new-auth-method |
| 57 | +# ... make changes ... |
| 58 | + |
| 59 | +# 2. Add changeset |
| 60 | +pnpm changeset |
| 61 | +# Select: @nylas/connect → minor → "Add new OAuth flow support" |
| 62 | + |
| 63 | +# 3. Commit and push |
| 64 | +git add .changeset/ |
| 65 | +git commit -m "feat: add new OAuth flow support" |
| 66 | +git push origin feature/new-auth-method |
| 67 | + |
| 68 | +# 4. Create PR and merge to main |
| 69 | +# 5. Release PR is automatically created |
| 70 | +# 6. Review and merge release PR |
| 71 | +# 7. Packages are published automatically! |
| 72 | +``` |
| 73 | + |
| 74 | +## Troubleshooting |
| 75 | + |
| 76 | +### Release PR Not Created |
| 77 | +- Check that changesets exist in `.changeset/` (not just config files) |
| 78 | +- Verify the GitHub Action ran successfully |
| 79 | +- Ensure you have the required permissions |
| 80 | + |
| 81 | +### Publishing Fails |
| 82 | +- Verify `NPM_TOKEN` secret is set correctly |
| 83 | +- Check NPM token has publish permissions for `@nylas` scope |
| 84 | +- Ensure package versions don't already exist on NPM |
| 85 | + |
| 86 | +### Manual Recovery |
| 87 | +If automation fails, you can manually release: |
| 88 | + |
| 89 | +```bash |
| 90 | +# Update versions |
| 91 | +pnpm version |
| 92 | + |
| 93 | +# Build and publish |
| 94 | +pnpm publish |
| 95 | + |
| 96 | +# Create git tags |
| 97 | +git push --follow-tags |
| 98 | +``` |
0 commit comments