Library releases

Changesets makes library release intent explicit now that UI and the private website are separate workspaces. A website fix must not become a library patch. Git-hygiene remains responsible for branch names and conventional commits; git-cliff no longer generates new releases. Its configuration is retained for historical reference, not as a second active release pipeline.

Sources of truth

The root and website are private and are not versioned or published. Existing v0.4.0 and older tags stay unchanged. This migration creates no new version.

Contributor workflow

For a user-visible UI change, run pnpm changeset, select @chitrank2050/monoline-ui, choose patch/minor/major, and describe the consumer impact. Commit the generated Markdown file with the implementation.

Use a clear first line, for example fix(select): Preserve focus after closing. Conventional prefixes supply the website’s semantic groups. Additional paragraphs belong in the package/GitHub release notes; the current timeline displays the headline. A major changeset marks its timeline entry as breaking. Commit SHAs and author names come from Git; the adapter does not guess PR numbers or GitHub handles.

Website, test, and CI-only work needs no library changeset. An explicit no-release decision can be recorded with pnpm changeset --empty. A library runtime dependency update still needs a changeset even when application source did not change.

Use pnpm release:status to inspect pending intent. The underlying Changesets CLI can exit nonzero when library files differ from main but no changeset exists; that is a request to review release intent, not an automatic version bump.

Maintainer workflow

flowchart LR
    A[Merge changes with release intent] --> B[Dispatch Prepare on main]
    B --> C[Review generated release PR]
    C --> D[Merge release PR]
    D --> E[Validate exact commit and version]
    E --> F[Tag verified commit]
    F --> G[Publish npm and JSR]
    G --> H[Create GitHub release]

1. Dispatch UI Release 1 - Prepare PR on main. No pending library changes means no release PR and no version mutation. Stable releases only are supported.
2. Review the consumed changesets, package version/changelog, synchronized JSR version, lockfile, and new website entry. Root historical notes are not regenerated.
3. Merge the generated release/vX.Y.Z PR after required checks pass. Finalize checks out its exact merge commit for every source-consuming job. The requested tag, npm manifest, JSR manifest, and prepared release notes must agree. If newer changesets land, rerun Prepare and review its updated PR before merging; Finalize refuses to publish with unconsumed UI changesets; independent Docs changesets remain pending.
4. Finalize validates static checks, package consumers, and the production website build before tagging. GitHub release creation waits for both registries and uses only the prepared package notes, not a new Git history scan.

Do not use changeset publish directly: it does not run the repository’s JSR job or verification gates. pnpm release:version is a mutating preparation command, intended for the Prepare workflow; running it locally consumes pending changesets.

Failure recovery and boundaries

• npm scans uploads before versions become installable. After a successful upload, the helper polls for roughly 20 minutes; the npm job has a 25-minute timeout. A longer review can still time out. Check registry availability and retry the same release rather than preparing another version.
• If one registry fails after the other succeeds, use GitHub’s Re-run failed jobs on that same run. Never move an existing tag. npm retries compare published package contents with the attested candidate; JSR retries compare the complete file set, exports and checksums with the verified source after Deno’s publication rewrites (resolved imports, type comments and JSX pragmas). Lookup failures stop publishing instead of treating a registry outage as an absent version.
• Manual Finalize dispatch runs from main but checks out the requested existing vX.Y.Z tag. All downstream jobs use the verified commit SHA. Recovery cannot publish current main under an older version. An existing GitHub release must contain the matching tarball; missing or conflicting assets require review.
• UI JSR verification loads tools from the immutable workflow commit, separately from the tagged package source. Once a verifier fix lands on main, dispatch UI Release 2 - Finalize Tag from main with the existing tag and target github-release to verify both registries and create the missing release. Re-running an old run uses its old workflow, so it cannot apply this fix.
• JSR provenance is required by default, including for existing versions. If a confirmed upstream failure left an already published version without provenance, explicitly select disabled-for-recovery. Contents must still pass verification; the workflow warns and adds the exception to the GitHub release notes. This does not restore the missing attestation. Never move the tag or republish another source tree under the same version.
• Preparation requires committed changesets for attribution. It rejects prerelease mode, JSR version drift, duplicate timeline versions, unsupported publishable packages and cross-package Changesets before versioning. A failed local generation may leave partial generated files; inspect the diff rather than committing it blindly.
• Existing bot permissions, npm credentials, and JSR authentication remain unchanged. No secrets, remote settings, tags, or packages are changed by this migration itself.
• New public packages need explicit publishing and tag policies before this adapter accepts them. Changesets supports a larger workspace; our current publisher supports only the UI package; Docs has its own npm-only workflow. Changelog UI redesign, registry, and blocks remain separate work.

CI tests exercise the real Changesets CLI in temporary Git workspaces, including no-release work, attribution, historical preservation, duplicate summaries, and rejected version mismatches. They do not publish to either registry.

References

• Changesets configuration
• Changesets CLI

Independent package releases

UI and Docs can have separate pending Changesets at the same time. Dispatch the prepare workflow for the package you want to release: UI Release 1 - Prepare PR for UI, or Docs Release 1 - Prepare PR for Docs. Preparation uses Changesets version --ignore to leave the other package’s version, changelog and Changesets untouched. Finalization checks only the selected package’s unconsumed intent. Split a Changeset that names both packages into separate files before preparing; shared release intent cannot be consumed by only one package.

UI uses vX.Y.Z tags and supports npm, JSR and GitHub release recovery targets. Docs uses docs-vX.Y.Z tags and supports npm and GitHub release targets. Both manual recovery workflows validate the requested stable tag before checkout and use its exact commit throughout. Missing tags fail; recovery does not create an old version from current main. These are package release workflows, not hosting provider deployments.

JSR recovery treats missing version metadata as absence, but missing manifests, lookup failures and checksum mismatches as errors. A mismatch must stop the run without attempting to publish over the existing version.

JSR publishing requires provenance by default for automatic releases and manual recovery. Select disabled-for-recovery only when recovering a confirmed upstream provenance outage; normal retries keep required. Registry identity and checksum verification still apply in recovery mode.