Peekaboo/RELEASING.md

Releasing Peekaboo MCP

This document outlines the steps to release a new version of the @steipete/peekaboo-mcp NPM package.

Pre-Release Checklist

1. Ensure Main Branch is Up-to-Date:

   • Pull the latest changes from the main branch (main or master).
   • git pull origin main

2. Create a Release Branch (Optional but Recommended):

   • Create a new branch for the release, e.g., release/v1.0.0-beta.3.
   • git checkout -b release/vX.Y.Z

3. Update Version Number:

   • Decide on the new semantic version number (e.g., 1.0.0-beta.3, 1.0.0, 1.1.0).
   • Update the version field in package.json.

4. Update Documentation:

   • README.md: Ensure it accurately reflects the latest features, installation instructions, and any breaking changes.
   • docs/spec.md: If there are changes to tool schemas or server behavior, update the detailed specification.
   • Any other relevant documentation.

5. Update CHANGELOG.md:

   • Add a new section for the upcoming release version (e.g., ## [1.0.0-beta.3] - YYYY-MM-DD).
   • List all notable changes (Added, Changed, Fixed, Removed, Deprecated, Security) under this version.
   • Replace YYYY-MM-DD with the current date.

6. Run All Tests:

   • Ensure all unit, integration, and E2E tests are passing.
   • npm test (or npm run test:all if that's more comprehensive for your setup).

7. Build the Project:

   • Run the build script to compile TypeScript and the Swift CLI.
   • npm run build:all (as defined in package.json).

8. Commit Changes:

   • Commit all changes related to the version bump, documentation, and changelog.
   • git add .
   • git commit -m "Prepare release vX.Y.Z"

9. Merge to Main Branch (If Using a Release Branch):

   • Merge the release branch back into the main branch.
   • git checkout main
   • git merge release/vX.Y.Z --no-ff (using --no-ff creates a merge commit, which can be useful for tracking releases).
   • git push origin main

Publishing to NPM

1. NPM Publish Dry Run:

   • This step is crucial to verify what files will be included in the package without actually publishing.
   • npm publish --access public --tag <your_tag> --dry-run
     • Replace <your_tag> with the appropriate tag (e.g., beta, latest). For pre-releases, always use a specific tag like beta or rc.
     • --access public is needed for scoped packages if they are intended to be public.
   • Carefully review the list of files. Ensure it includes dist/, peekaboo (the Swift binary), package.json, README.md, CHANGELOG.md, and LICENSE. Ensure no unnecessary files are included.

2. Actual NPM Publish:

   • If the dry run is satisfactory, proceed with the actual publish command.
   • npm publish --access public --tag <your_tag>

Post-Publish Steps

1. Create a Git Tag:

   • Create a Git tag for the new version.
   • git tag vX.Y.Z (e.g., git tag v1.0.0-beta.3)

2. Push the Git Tag:

   • Push the tag to the remote repository.
   • git push origin vX.Y.Z

3. Create a GitHub Release (Optional):

   • Go to the GitHub repository's "Releases" section.
   • Draft a new release, selecting the tag you just pushed.
   • Copy the relevant section from CHANGELOG.md into the release description.
   • You can also attach any build artifacts (like the peekaboo binary or the .tgz NPM package) to the GitHub release for direct download if desired.

4. Announce the Release (Optional):

   • Announce the new release on relevant channels (e.g., team chat, Twitter, project website).

---

Note on prepublishOnly: The package.json contains a prepublishOnly script that runs npm run build:all. This ensures that the project is always built before publishing.