nylas-nodejs-release

name: nylas-nodejs-release description: >- Prepares nylas-nodejs SDK releases on a versioned release branch with CHANGELOG updates, version bump, git tag, and PR body. Stops for the maintainer to run npm publish, then after confirmation creates the GitHub Release from the tag. Use when the user wants to ship a new SDK version, cut a release branch, update CHANGELOG.md, npm version, tag, open a release PR, publish to npm, or create a GitHub Release.

nylas-nodejs SDK release

Automate everything up to npm publish and GitHub Release creation after merge, with explicit human checkpoints for publishing and confirmation.

Principles

• Never commit or paste npm tokens, .npmrc secrets, or session credentials. Publishing uses npm login on the maintainer’s machine only.
• Release branch name: vX.Y.Z-release (example: v8.0.5-release).
• CHANGELOG follows Keep a Changelog at repo root: CHANGELOG.md.
• Traceability: Each changelog line should reference the relevant PR, commit(s), and closed issues where applicable (see PR description template below).

When the user starts a release

Ask for (if not already given):

1. Target semver X.Y.Z (no leading v in the version number for package.json).
2. Release date for the changelog (ISO-style: YYYY-MM-DD).
3. Whether this is latest or canary (see reference.md for canary/dist-tag).

Phase 1 — Branch and changelog (agent)

1. Ensure work is based on main with intended changes already merged (or document what is included).
2. Create and checkout vX.Y.Z-release from main:
   • git fetch origin main && git checkout -b vX.Y.Z-release origin/main
3. CHANGELOG.md:
   • If there is an ## [Unreleased] section: rename it to ## [X.Y.Z] - YYYY-MM-DD and fill sections (Added / Changed / Fixed / Breaking change, etc.).
   • If there is no Unreleased section: add a new top section after the intro paragraphs:
     • ## [X.Y.Z] - YYYY-MM-DD
   • Match existing style (see recent entries in CHANGELOG.md).
   • For each bullet, include PR/issue links like ([#NNN](https://github.com/nylas/nylas-nodejs/pull/NNN)) where possible.
4. Commit: chore(release): prepare vX.Y.Z (or team convention).
5. Push the branch: git push -u origin vX.Y.Z-release.

Stop and show the user: branch name, diff summary, and the new changelog section.

Phase 2 — Version, tag, PR (agent; user may need to run commands locally)

1. Pre-flight before npm run build / publish: Confirm there are no test files under src/ that would ship in the package (team rule).
2. Run npm version X.Y.Z (semver only; no v prefix in the command argument).
   • This bumps package.json, runs the version lifecycle script (export-version updates src/version.ts for the User-Agent), creates a commit, and a git tag vX.Y.Z (default npm tag prefix).
3. Push branch and tags:
   • git push origin vX.Y.Z-release
   • git push origin vX.Y.Z (or git push origin --tags if that is the team norm—prefer pushing the explicit tag to avoid stray tags).

Open a PR vX.Y.Z-release → main with this description template:

## Release vX.Y.Z (YYYY-MM-DD)

### Changelog

[Paste the full `## [X.Y.Z] - YYYY-MM-DD` section from CHANGELOG.md]

### References

For each line above, link the implementing commits and closed issues (example pattern):

- **Summary of the change** — commit `abc1234` / PR #123 / closes #456 …

(Add community / contributor credits if applicable.)

Ask the user to wait for CI green on the PR.

4. After CI passes, run npm run build on the release branch to validate the artifact locally.

Checkpoint — npm publish (maintainer only)
Tell the user clearly:

• Publishing requires npm credentials with publish rights, configured via npm login on their machine (see reference.md for prerequisites). Do not store secrets in the repo.
• They should run npm publish (or npm publish --tag canary for canary) from the clean release branch after CI passes and build is verified.
• They should verify the package on npm when done.

Wait until the user explicitly confirms both:

1. npm: “The package is published (and dist-tag is correct).”
2. Git: “The release PR is merged to main.”

Do not create the GitHub Release until both are confirmed.

Phase 3 — GitHub Release (agent, after confirmation)

Only after the user confirms published + PR merged:

1. Ensure local main is up to date: git fetch origin main && git checkout main && git pull origin main.
2. Verify tag vX.Y.Z exists on the remote (merged release flow should have the tag from npm version; if not, stop and ask).
3. Create the GitHub Release from tag vX.Y.Z with:
   • Title: vX.Y.Z (or nylas vX.Y.Z to match past releases).
   • Body: Same changelog content and PR/issue/commit references as the merged PR; tag community contributors for credit when applicable.

Prefer the gh CLI when available:

gh release create "vX.Y.Z" --title "vX.Y.Z" --notes-file - <<'EOF'
<Paste release notes; same as PR/changelog>
EOF

If gh is not available, give exact GitHub UI steps: Repository → Releases → Draft a new release → choose tag vX.Y.Z → paste notes.

Copy-paste checklist

Track progress in the chat:

Phase 1 — Prep
- [ ] Branch vX.Y.Z-release from main
- [ ] CHANGELOG [X.Y.Z] section complete with links
- [ ] Pushed branch

Phase 2 — Version & PR
- [ ] No stray tests under src/
- [ ] npm version X.Y.Z (version.ts + tag)
- [ ] Pushed branch + tag
- [ ] PR opened with changelog + references
- [ ] CI green; npm run build OK
- [ ] User ran npm publish (or canary)
- [ ] User confirmed published + PR merged

Phase 3 — GitHub
- [ ] gh release create (or UI) from vX.Y.Z with full notes

Additional topics

• Canary releases, promoting latest, and verifying npm: reference.md
• Example release PR style: https://github.com/nylas/nylas-nodejs/pull/590