chore: manual release process

[aaronschweig]

Closes #229

Separates validating a version from cutting a release: main builds and tests only, and releases become an explicit, manually triggered action owned entirely by this repo.

Changes

• pipeline.yaml: self-contained build + test for PRs and main pushes (no publish, no version bump).
• release.yaml: manual workflow_dispatch release — compute version → build/test → changelog → npm publish (both packages, OIDC) → commit/tag/push → GitHub Release. Publish happens before tagging; branch-aware (github.ref_name) for backports; dry-run and release-as inputs.
• pr-title.yaml: required Conventional Commits check on PR titles (load-bearing under squash-merge).
• Versioning: semver-action with prefix: "", minorList: feat, patchList: fix, perf, silent no-ops, plus a pre-1.0 major→minor guard.
• Changelog: cliff.toml + seeded CHANGELOG.md; scripts/update-changelog.mjs inserts each release section beneath a marker (avoids --prepend clobbering the header).
• Docs: commit conventions/increment table in CONTRIBUTING.md; new RELEASING.md (normal release, dry-run, backports, 1.0.0 promotion).
• projects/ngx/package.json: bumped stale 0.1.0 → 0.18.11.

Deviations worth noting

• check-format is commented out in CI: ~74 pre-existing files fail Prettier today. Tracked as an immediate follow-up in RELEASING.md.
• Changelog uses a marker-insert script instead of git cliff --prepend (prepend strips the file header).

Prerequisites (repo admin, before first release)

• Make the PR Title check required; allow github-actions[bot] to push main/release/*.

Recommended first real check after merge: run release.yaml with dry-run: true on main.

Summary by CodeRabbit

• New Features

  • Added automated release workflows supporting versioning, changelog generation, dry runs, package publishing, tagging, and GitHub Release creation.
  • Added pull request title validation using Conventional Commit conventions.
  • Added automated build and test verification.

• Documentation

  • Added release procedures, contribution guidelines, commit conventions, and changelog documentation.
  • Added automated changelog update support and the 0.18.11 release baseline.

• Chores

  • Updated the package version to 0.18.11.
  • Improved workflow permissions and release safeguards.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request replaces shared CI and publishing workflows with repository-owned validation and release automation. It adds Conventional Commit validation, semantic versioning, changelog generation, npm publishing, tagging, GitHub Release creation, package version updates, and release documentation.

Changes

Release process

Layer / File(s)	Summary
CI and pull request validation .github/workflows/pipeline.yaml, .github/workflows/pr-title.yaml	The repository now runs Node 24 dependency installation, tests, and builds with read-only contents access. Pull request titles are checked against the allowed Conventional Commit types.
Release policy and changelog contracts cliff.toml, CHANGELOG.md, CONTRIBUTING.md, RELEASING.md	Conventional Commit parsing, changelog rendering, release rules, backport procedures, dry-run commands, and the 0.18.11 baseline release are documented and configured.
Release selection and version resolution .github/workflows/release.yaml	The manual workflow detects the branch baseline, calculates semantic version changes, supports explicit versions and dry runs, and applies pre-1.0 major-bump handling.
Build, publish, and finalize release .github/workflows/release.yaml, scripts/update-changelog.mjs, projects/ngx/package.json, CHANGELOG.md	The workflow builds both packages, updates versions and changelog content, publishes both npm packages, commits and pushes release changes, creates tags and GitHub Releases, and skips mutations during dry runs.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ReleaseOperator
  participant GitHubActions
  participant GitHistory
  participant GitCliff
  participant NpmRegistry
  participant GitHub
  ReleaseOperator->>GitHubActions: Dispatch release with ref, dry-run, and release-as inputs
  GitHubActions->>GitHistory: Detect baseline tag and calculate semantic version
  GitHistory-->>GitHubActions: Return baseline tag and resolved version
  GitHubActions->>GitCliff: Generate release notes
  GitCliff-->>GitHubActions: Return release section
  GitHubActions->>NpmRegistry: Publish both npm packages
  GitHubActions->>GitHub: Commit changes, push tag, and create GitHub Release

Loading

Possibly related issues

• #248: The issue describes the same repository-owned release workflow, pipeline, and pull request title validation changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes cover repository-owned CI, manual releases, PR-title validation, changelog tooling, package versioning, and release documentation requested in [#229].
Out of Scope Changes check	✅ Passed	The workflow, documentation, changelog, configuration, and package-version changes directly support the release-process objectives in [#229].
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: introducing a manual release process.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/release-process

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/pipeline.yaml:
- Line 23: Update the actions/checkout step to set persist-credentials to false,
ensuring the checkout token is removed from Git configuration before subsequent
npm commands run.

In @.github/workflows/release.yaml:
- Around line 158-188: The release workflow at .github/workflows/release.yaml
lines 158-188 must support idempotent reruns: check whether each package version
already exists in the registry before publishing, and safely skip completed
commit, tag, push, and GitHub Release operations while performing missing steps.
Update RELEASING.md lines 44-46 to remove the claim that reruns are safe until
this recovery behavior is implemented.
- Around line 15-17: Configure the release job’s environment as npm-release so
GitHub applies required reviewers and deployment branch restrictions for main
and release/* before executing the existing checkout, build, and publish steps.
Use the same npm-release environment name for npm Trusted Publishing; leave the
existing permissions unchanged.
- Around line 43-52: In .github/workflows/release.yaml lines 43-52, configure
the semver action with the selected branch via github.ref_name. In
.github/workflows/release.yaml lines 158-188, make publish recovery idempotent
so reruns safely handle already-published package versions; update RELEASING.md
lines 86-89 to document the corresponding manual recovery procedure if full
automation is not possible.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d0f0acd2-fbbe-4ddd-8f33-562de1547a5d

📥 Commits

Reviewing files that changed from the base of the PR and between f57b5e2 and 9fb16ed.

📒 Files selected for processing (9)

• .github/workflows/pipeline.yaml
• .github/workflows/pr-title.yaml
• .github/workflows/release.yaml
• CHANGELOG.md
• CONTRIBUTING.md
• RELEASING.md
• cliff.toml
• projects/ngx/package.json
• scripts/update-changelog.mjs

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

RELEASING.md (1)

70-71: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Validate release-as before resolving the version.

The override bypasses the pre-1.0 guard and passes directly to npm version, so prerelease, branch-incompatible, or lower versions can reach both publish steps. Accept only stable, non-decreasing, branch-compatible versions, with an explicit 1.0.0 promotion exception.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@RELEASING.md` around lines 70 - 71, Update the release workflow instructions
around the release-as input to require validation before version resolution:
accept only stable, non-decreasing versions compatible with the current branch,
while allowing the explicit 1.0.0 promotion exception; reject invalid overrides
before they reach either publish step or npm version.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@RELEASING.md`:
- Around line 70-71: Update the release workflow instructions around the
release-as input to require validation before version resolution: accept only
stable, non-decreasing versions compatible with the current branch, while
allowing the explicit 1.0.0 promotion exception; reject invalid overrides before
they reach either publish step or npm version.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 491b8242-bdd7-489a-a076-5ee39162d010

📥 Commits

Reviewing files that changed from the base of the PR and between 9fb16ed and 473e6ad.

📒 Files selected for processing (3)

• .github/workflows/pipeline.yaml
• .github/workflows/release.yaml
• RELEASING.md

🚧 Files skipped from review as they are similar to previous changes (2)

• .github/workflows/pipeline.yaml
• .github/workflows/release.yaml