# Release Process

Sarathi releases publish a coherent prompt, skill, checker, installer, and
documentation snapshot. Release tags are lightweight to consume but should be
prepared deliberately.

## Versioning

- Use `vMAJOR.MINOR.PATCH` Git tags, for example `v0.1.0`.
- Keep the tag version aligned with `pyproject.toml` and
  `skills/sarathi/manifest.json`.
- Use patch releases for fixes that do not change the intended SDLC behavior.
- Use minor releases for new prompts, checker rules, skill guidance, installer
  targets, or meaningful process behavior changes.
- Reserve major releases for incompatible command, artifact, checker, or install
  contract changes.

## Changelog Rules

- Every user-visible prompt, skill, checker, installer, or documentation change
  gets a `CHANGELOG.md` entry.
- Keep unreleased work under `## Unreleased`.
- Group entries under `Added`, `Changed`, `Fixed`, `Deprecated`, `Removed`,
  `Security`, or `Docs` as applicable.
- Before tagging, rename `## Unreleased` to `## X.Y.Z - YYYY-MM-DD`, add a fresh
  empty `## Unreleased` section above it, and make sure the date is the tag date.
- Do not list private implementation noise unless it affects maintainers,
  installers, checkers, prompt behavior, or generated artifacts.

## Release Preparation

1. Confirm the working tree is clean:

   ```sh
   git status --short --branch
   ```

2. Choose the next version and update both `pyproject.toml` and
   `skills/sarathi/manifest.json`.

3. Update `CHANGELOG.md`:

   - Move relevant entries from `Unreleased` into the versioned section.
   - Add or prune categories so the section is readable.
   - Keep a new empty `Unreleased` section at the top.

4. Run the full local gate:

   ```sh
   uv run python -m pre_commit run --all-files
   ```

5. Build and inspect the PyPI distributions:

   ```sh
   uv build
   uv run twine check dist/*
   ```

6. Run installer dry runs for the platforms available on the release machine, including
   the packaged command:

   ```powershell
   .\scripts\install.ps1 -DryRun
   ```

   ```sh
   bash scripts/install.sh --dry-run
   uv run sarathi-sdlc install --dry-run
   ```

   On Windows, the PowerShell dry run may also exercise the WSL companion path
   when WSL is available. On WSL, the Bash dry run may exercise the Windows
   companion path when `powershell.exe` is available.

7. Commit the release prep:

   ```sh
   git add pyproject.toml skills/sarathi/manifest.json CHANGELOG.md
   git commit -m "Release vX.Y.Z"
   ```

8. Merge the release preparation through a reviewed PR. Create an annotated tag from the
   merged `master` commit:

   ```sh
   git tag -a vX.Y.Z -m "sarathi vX.Y.Z"
   ```

9. Push the tag:

   ```sh
   git push origin vX.Y.Z
   ```

   `.github/workflows/release.yml` verifies the tag and metadata, reruns all checks,
   builds the wheel and source distribution, and publishes them through the `pypi`
   environment and PyPI Trusted Publishing. After PyPI succeeds, it creates the GitHub
   Release and attaches both distributions. The final step is safe to rerun: an existing
   release receives refreshed attachments instead of a duplicate release. Do not publish
   the files or create the GitHub Release manually.

10. Confirm the release on both PyPI and GitHub, then optionally deploy locally from the
    tagged commit:

   ```powershell
   .\scripts\install.ps1
   ```

   ```sh
   uv tool upgrade sarathi-sdlc
   sarathi-sdlc install
   ```

## Tag Corrections

Avoid rewriting a published tag. If a pushed release tag is wrong, prefer a new
patch release. Delete and recreate a tag only when it has not been consumed and
the maintainers explicitly agree.
