Skip to content

RELEASING.md

Latest commit

 

History

History
84 lines (62 loc) · 4.03 KB

RELEASING.md

File metadata and controls

84 lines (62 loc) · 4.03 KB
Raw

Releasing

Ragmir publishes to npm through the protected Release npm GitHub Actions workflow on main. Do not publish from a local machine.

Release Flow

  1. Start feature work from develop on a feature/*, fix/*, or chore/* branch.
  2. Open a pull request into develop and wait for required checks.
  3. From main, prepare a release/* branch containing the validated develop tree, then open a release pull request into main.
  4. Let the Release npm workflow run on main, or dispatch it manually from main.
  5. Approve the protected npm-publish environment when GitHub asks for review.
  6. Verify all three npm packages, the curated GitHub release notes, and release artifacts.
  7. Build and deploy the static landing through the external deployment process, then verify the published package version and canonical site URL.

For every release, verify that npm metadata declares AGPL-3.0-only and that each tarball contains LICENSE, COMMERCIAL-LICENSE.md, and NOTICE. The protected validation gate enforces this policy.

The workflow runs pnpm validate, then semantic-release derives the next version from Conventional Commits. It prepares and publishes, in order, @jcode.labs/ragmir-tts, @jcode.labs/ragmir-chat, and @jcode.labs/ragmir, all with npm provenance. Installing Core still keeps Chat and TTS optional.

The repository intentionally contains no cloud-vendor landing configuration and the npm workflow does not deploy the site. The external deployment must build with the released version in PUBLIC_RAGMIR_VERSION. Production must use PUBLIC_RAGMIR_LANDING_URL=https://ragmir.com; staging must use its own public URL so canonical and robots metadata cannot fall back to production.

Release Notes Contract

The promotion commit on main is the public source for the GitHub release. Its body must contain these exact sections, each with at least one concise bullet:

fix(release): improve public documentation and release communication

Release highlights:
- make Ragmir easier to understand and adopt without hiding its technical guarantees

Release details:
- **Documentation:** shorten every README and route advanced behavior to focused guides
- **Landing:** present one clear hero statement and keep SEO/GEO metadata aligned
- **Release automation:** publish curated notes with highlights, details, verification, and install links

Verification:
- pass pnpm validate and the Linux x64 and macOS ARM64 CI matrix
- verify the English and French production pages in a browser

scripts/semantic-release-notes.mjs converts those sections into a GitHub release with highlights, grouped changes, verification evidence, install commands, package links, artifacts, and a full changelog link. Semantic release stops before publishing if a release commit omits the contract.

Write the body from the complete develop to main delta. Mention user-visible outcomes and the substantial engineering work behind them, not file counts, implementation trivia, or a raw list of commit subjects. Keep each line within the repository's commitlint limit.

Versioning Notes

  • feat: creates a minor release.
  • fix: and docs: create patch releases.
  • feat!: or a BREAKING CHANGE: footer creates a major release.
  • scope: landing is ignored for npm versioning because the landing is not an npm package.

The first AGPL release is v3.0.0 because changing the public license from MIT is a breaking legal change. Release notes must state that earlier versions keep their original license and link to the commercial licensing option.

For CLI compatibility releases, make the migration explicit in the Conventional Commit body or footer. For example, the ragmir to rgr rename must mention that ragmir remains as a deprecated compatibility bin and users should migrate scripts to rgr.

Required Local Checks

Run the full gate before opening or updating a release pull request:

pnpm validate

For narrower preflight while iterating, use the package-level checks that match the edited area, then run pnpm validate before release.