@xpertss/projen-types 0.0.1 → 0.0.3

package/release-publishing.md

@@ -2,133 +2,124 @@
 
 ## Scope
 
-This document defines the commit and release discipline required for the `release` workflow (`.github/workflows/release.yml`, generated by projen from `.projenrc.ts`) to publish correctly to npm and GitHub Releases.
+This document defines how to trigger a release of `@xpertss/projen-types` and the commit discipline required for a release to happen. It applies to the `release` workflow (`.github/workflows/release.yml`, generated by projen from `.projenrc.ts`).
 
-Keying requirement: **the first line of your commit message is the release control plane.** Everything else (triggering, versioning, publishing) is automatic once commits follow this spec.
+**A release happens when a run of the `release` workflow finds at least one releasable commit since the last release tag** — a commit whose subject is typed `feat:` or `fix:` (see §2). Runs are started by any push to `main` (or manually, §1). A run whose window contains no `feat:`/`fix:` commits is a **green no-op** that publishes nothing — `docs:`, `ci:`, `chore:`, and other commits never release on their own.
 
 Key words "MUST", "MUST NOT", "SHOULD" are to be interpreted as described in RFC 2119.
 
-## 1. Release triggering
+## 1. Triggering a release
 
-- **Any push to `main`** starts the `release` workflow — direct push or merged PR, both are equivalent. There is no per-release approval step; every push to `main` is a release *attempt*.
-- The workflow can also be started manually: Actions → `release` → **Run workflow** (optional `dry_run` input; when true, everything runs except the actual `npm publish`).
-- A push that produces nothing releasable (see §3) is a **no-op run**: green, no tag, no npm publish, no GitHub release. This is expected behavior, not an error.
+- **Any push to `main`** starts the `release` workflow — direct push or merged PR. The run publishes only if the window since the last release tag contains a releasable commit (below); otherwise it is a no-op.
+- The workflow can also be started manually: GitHub → **Actions** → `release` → **Run workflow** (optional `dry_run = true` runs everything except the actual `npm publish`) — useful for re-running after a failed build or to confirm a no-op window.
+- At start of the run, the toolchain lists the **releasable commits** between the last release tag (`vX.Y.Z`) and `HEAD`: all non-merge commits whose subject matches `feat:` or `fix:` (with an optional scope and an optional `!`, e.g. `feat(parser)!: ...`).
+  - **≥ 1 releasable commit** → the run bumps the version, builds, and publishes to npm and GitHub Releases.
+  - **0 releasable commits** (e.g. only `docs:`, `ci:`, `chore:`, or unprefixed commits in the window) → the run is a **no-op**: green, no tag, no npm publish, no GitHub release. This is expected behavior, not an error.
 
-## 2. Commit message rules (MUST)
+## 2. Commit message rules
 
 ### 2.1 Format
 
-Commit messages MUST use the [Conventional Commits](https://www.conventionalcommits.org/) format. Only the **first line (subject)** is parsed, in the form:
+Commit messages MUST use the [Conventional Commits](https://www.conventionalcommits.org/) format. Only the **first line (subject)** is parsed for the type, in the form:
 
 ```
 type(scope)!: description
 ```
 
-- `type` — required, lower-case, from the table in §2.2.
+- `type` — lower-case; `feat` or `fix` makes the commit releasable (see §1).
 - `scope` — optional, free-form (e.g. `fix(parser): ...`).
 - `!` — optional breaking-change marker, see §2.3.
 - `description` — imperative mood preferred ("add", not "added"/"adds").
 
-### 2.2 Types and their effect on the version
+### 2.2 Releasable types and the version bump
 
-| First line starts with | Bump level | Example `0.0.0` → |
+Only `feat:` and `fix:` commits are releasable. When a release run does release, the bump level for the window is:
+
+| Window since last tag | Bump level | Example `0.1.0` → |
 |---|---|---|
-| `feat:` | **minor** | `0.1.0` |
-| `fix:` | **patch** | `0.0.1` |
-| `perf:` | **patch** | `0.0.1` |
-| any type + breaking marker (§2.3) | **major** | `1.0.0` |
-| `chore:`, `docs:`, `style:`, `refactor:`, `test:`, `build:`, `ci:` | **none** | (no bump) |
-| anything else / no prefix | **none** | (no bump) |
+| Breaking change present (§2.3) | **major** | `1.0.0` |
+| Else any `feat:` commit | **minor** | `0.2.0` |
+| Else (only `fix:` commits) | **patch** | `0.1.1` |
+
+Within one window, the highest level wins.
+
+**All commits since the last tag are included in the release**, not only the releasable ones — `docs:`, `ci:`, `chore:`, and other commits appear in the generated release notes (under an "Other" heading) and are part of the released content. They simply do not, on their own, cause a release to happen.
 
 ### 2.3 Breaking changes
 
 A change that is incompatible with existing consumers MUST be marked explicitly, one of:
 
 - `!` directly before the colon: `feat!: drop legacy option`
-- or a `BREAKING CHANGE:` paragraph in the commit **body** (for any type).
+- or a `BREAKING CHANGE:` paragraph in the commit **body** (the body, not the subject).
 
-Unmarked breaking changes are the one real hazard in this scheme: they will silently ship as a minor/patch bump.
+Because the releasable-commits check (§1) only inspects commit **subjects**, a breaking change MUST be carried by a `feat:`/`fix:` commit. A `BREAKING CHANGE:` note on any other commit type (e.g. `refactor:`) will never be released.
 
 ### 2.4 Examples
 
 | Message | Effect |
 |---|---|
-| `feat: add Java project scaffold` | minor bump |
-| `fix: correct dependency range in .projenrc.ts` | patch bump |
-| `feat!: remove deprecated option X` | major bump |
-| `Updated the README` | no bump — shipped in the next releasable window, listed under "Other" in release notes |
-| `one more fix` | no bump — contains the word "fix" but has no `fix:` prefix |
-
-## 3. Versioning model (verified behavior)
-
-Verified against projen 0.103.23 (`lib/release/bump-version.js`) and `commit-and-tag-version@^12` (the bump engine in the `bump` task, `.projen/tasks.json`).
-
-1. **Baseline** = the latest release tag on `main` (`vX.Y.Z`). The window being evaluated = all commits after that tag.
-2. **First release (no tag exists) never bumps** — by design it tags and publishes the version currently in `package.json` (this project: `0.0.0`).
-3. **Subsequent releases** bump according to the *highest* level present in the window: major > minor > patch. `feat:` + `fix:` in the same window → minor.
-4. **No releasable commits in the window → `bump: "none"`** → the `check_tag_exists` gate (`release.yml`) skips both publish jobs → no-op run.
-5. Version numbers are owned by the release toolchain. `package.json` `version` is written by the bump step and restored afterwards (`unbump`); the working copy must never show a drifted version.
-6. The bump step is skipped entirely when the latest commit on `main` is `chore(release): ...` (the auto-generated release commit) — releases do not self-trigger.
-
-### 3.1 What non-conventional commits do
-
-Commits without a recognized prefix:
-
-- do **not** trigger a release,
-- do **not** bump the version,
-- are **not** lost — they are shipped in the next release that the window produces (all commits since the last tag are published together),
-- appear under an **"Other"** heading in the generated release notes instead of "Features"/"Bug Fixes".
+| `feat: add Java project scaffold` | releasable; minor bump |
+| `fix: correct dependency range in .projenrc.ts` | releasable; patch bump |
+| `feat!: remove deprecated option X` | releasable; major bump |
+| `fix!: change default of option Y` | releasable; major bump |
+| `docs: update publishing guide` | **not releasable** — no release unless the window also has a `feat:`/`fix:` |
+| `ci: pin node version` | **not releasable** — no release unless the window also has a `feat:`/`fix:` |
+| `Updated the README` (no prefix) | **not releasable** |
+| `chore(release): 0.0.1` (auto-generated) | never counted — filtered out of the window |
 
-## 4. Release lifecycle (what CI does per run)
+## 3. What a release run does
 
-Per push to `main`, in order:
+Per run, in order:
 
-1. `release` job runs `npx projen release` = `rm -fr dist` → **bump** (resolve latest tag → suggest bump from window → apply: new version in `package.json`, tag, changelog to `dist/changelog.md`) → **build** (jsii) → **unbump** → `git diff` must be clean. A build failure aborts the run before anything is published.
-2. Gates: `tag_exists` (is `dist/releasetag.txt`'s tag already on origin?) and `latest_commit == github.sha` (did someone push a newer commit mid-run?).
+1. The `release` job runs `npx projen release` = `rm -fr dist` → **bump** (resolve latest tag → list releasable commits → if none, stop as no-op; if any, set the new version in `package.json`, write the changelog to `dist/changelog.md`) → **build** (jsii) → **unbump** → `git diff` must be clean. A build failure aborts the run before anything is published.
+2. Gates: `tag_exists` (is the computed release tag already on origin?) and `latest_commit == github.sha` (did someone push a newer commit mid-run?).
 3. If gated through, `Publish to npm` and `Publish to GitHub Releases` run in parallel:
    - **npm:** `publib-npm` with `NPM_TRUSTED_PUBLISHER=true` (OIDC, no token; see `spec/npm-publishing-setup.md`). A version that is already on the registry is reported as `SKIPPING: already published` — green, not an error.
    - **GitHub:** `gh release create vX.Y.Z --target <sha>` with the generated changelog as body; this also creates/pushes the `vX.Y.Z` tag.
 4. The `chore(release): vX.Y.Z` commit (author `github-actions[bot]`) lands on `main`.
 
-## 5. Rules
+## 4. Rules
 
 ### MUST
 
-- Prefix every user-facing change with `feat:` (new capability) or `fix:` (bug fix); `perf:` for performance fixes.
-- Mark breaking changes with `!` or a `BREAKING CHANGE:` body paragraph.
-- Use the imperative mood in the subject.
+- Type commits `feat:` or `fix:` when the change should be part of a release.
+- Mark breaking changes with `!` or a `BREAKING CHANGE:` **body** paragraph, on a `feat:`/`fix:` commit (§2.3).
+- Treat a push to `main` whose window contains `feat:`/`fix:` commits as an imminent release — review accordingly.
 - Verify after each release: `npm view @xpertss/projen-types version` and the GitHub **Releases** page.
 
 ### MUST NOT
 
+- Push a `feat:`/`fix:` commit to `main` unless you are ready to publish — the run it triggers will release.
 - Edit `package.json` `version` by hand, or add a `version` field to `.projenrc.ts` — the release toolchain owns version numbers.
 - Move, rename, or rewrite release tags (`vX.Y.Z`) on `main` — the tag is the version baseline.
 - Force-push `main` — it desyncs the tag baseline from history.
 - Edit `.github/workflows/release.yml` directly — edit `.projenrc.ts` and run `npx projen`. In particular, renaming the workflow file or changing the `release_npm` job would orphan the npm **trusted publisher** configuration (see `spec/npm-publishing-setup.md`, step 3).
-- Rely on non-prefixed commits to trigger or bump a release.
 
 ### SHOULD
 
-- One logical change per commit; keep the subject ≤ 72 chars.
-- If merging via PR, use **squash merge** and make the *squash title* the conventional message — it replaces all underlying commit subjects, so a PR full of `feat:` commits merged as "stuff" releases nothing.
-- Batch work so each window ends with at least one prefixed commit, if the window contains releasable work.
+- Use **squash merge** for PRs and make the *squash title* the conventional message — it replaces all underlying commit subjects and therefore decides whether the merged change is releasable.
+- Use the imperative mood in the subject; one logical change per commit; subject ≤ 72 chars.
+- Keep a releasable (`feat:`/`fix:`) commit in the window whenever you intend a release to include a given set of changes; otherwise bundle the changes into a `feat:`/`fix:` PR.
 
-## 6. Edge cases and known behaviors
+## 5. Edge cases and known behaviors
 
 | Situation | Outcome |
 |---|---|
-| Push with only non-prefixed commits | no-op run (green, nothing published) |
-| `feat:` + `fix:` in one window | minor bump (highest wins) |
-| Re-running the workflow for the same version | `tag_exists` gate skips publishing |
-| Version already on npm (e.g. published manually beforehand) | `publib-npm` prints `SKIPPING: already published`, job is green |
-| Two pushes in rapid succession | concurrency group serializes; the second run's `latest_commit` gate handles drift |
-| Build fails | run aborts, no tag, no publish — push a fix and re-push |
-| `chore(release):` is the latest commit | bump step skips — no double release |
+| Push to `main` with `feat:`/`fix:` commits in the window | release run — minor / patch / major per §2.2 |
+| Push or manual run whose window has only non-releasable commits (`docs:`, `ci:`, …) | no-op run — green, nothing published |
+| Window contains `feat:` (no breaking) | minor bump (highest level wins) |
+| Breaking change marked per §2.3 on a `feat:`/`fix:` commit | major bump |
+| Run with no commits since the last release tag (e.g. re-run of the same HEAD) | no-op run |
+| Run for an already-published tag | `tag_exists` gate skips publishing |
+| Version already on npm (e.g. published manually beforehand) | `publib-npm` prints `SKIPPING: already published`, run is green |
+| Two runs in rapid succession | concurrency group serializes; the second run's `latest_commit` gate handles drift |
+| Build fails | run aborts, no tag, no publish — fix and trigger again |
+| `chore(release):` is the latest commit | excluded from the window — no double release |
 
 ## References
 
 - Workflow: `.github/workflows/release.yml` (projen-generated; source of truth is `.projenrc.ts`)
-- Bump engine: `commit-and-tag-version@^12` (task `bump`, `.projen/tasks.json`), projen builtins `release/resolve-latest-tag`, `release/suggest-version-bump`, `release/apply-version-bump`
-- Verified sources: projen 0.103.23 `lib/release/bump-version.js`, `lib/release/publisher.js`; publib 0.3.3 `bin/publib-npm`
+- Releasable-commits gate: `bump:releasable-commits` task (`.projen/tasks.json`) — `git log --no-merges --oneline $LATEST_TAG..HEAD -E --grep '^(feat|fix){1}(\(...\))?(!)?:...'`
+- Bump engine: `commit-and-tag-version@12` (task `bump`, `.projen/tasks.json`), projen builtins `release/resolve-latest-tag`, `release/suggest-version-bump`, `release/apply-version-bump`
 - Publishing credentials (OIDC trusted publisher, bootstrap, 2FA): `spec/npm-publishing-setup.md`
 - Conventional Commits: https://www.conventionalcommits.org/

package/lib/common/drift-check.d.ts

@@ -1,8 +0,0 @@
-import { github } from 'projen';
-/**
- * Steps that re-run projen and fail the job if the generated output no
- * longer matches what's committed - i.e. someone hand-edited a projen
- * managed file (package.json/pom.xml/.github/workflows/*.yml/...) without
- * going through .projenrc.
- */
-export declare function driftCheckSteps(projenCommand?: string): github.workflows.JobStep[];

package/lib/common/drift-check.js

@@ -1,18 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.driftCheckSteps = driftCheckSteps;
-/**
- * Steps that re-run projen and fail the job if the generated output no
- * longer matches what's committed - i.e. someone hand-edited a projen
- * managed file (package.json/pom.xml/.github/workflows/*.yml/...) without
- * going through .projenrc.
- */
-function driftCheckSteps(projenCommand = 'npx projen') {
-    return [
-        {
-            name: 'Check for projen drift',
-            run: `${projenCommand}\ngit diff --exit-code`,
-        },
-    ];
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZHJpZnQtY2hlY2suanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvY29tbW9uL2RyaWZ0LWNoZWNrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBUUEsMENBU0M7QUFmRDs7Ozs7R0FLRztBQUNILFNBQWdCLGVBQWUsQ0FDN0IsYUFBYSxHQUFHLFlBQVk7SUFFNUIsT0FBTztRQUNMO1lBQ0UsSUFBSSxFQUFFLHdCQUF3QjtZQUM5QixHQUFHLEVBQUUsR0FBRyxhQUFhLHdCQUF3QjtTQUM5QztLQUNGLENBQUM7QUFDSixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgZ2l0aHViIH0gZnJvbSAncHJvamVuJztcblxuLyoqXG4gKiBTdGVwcyB0aGF0IHJlLXJ1biBwcm9qZW4gYW5kIGZhaWwgdGhlIGpvYiBpZiB0aGUgZ2VuZXJhdGVkIG91dHB1dCBub1xuICogbG9uZ2VyIG1hdGNoZXMgd2hhdCdzIGNvbW1pdHRlZCAtIGkuZS4gc29tZW9uZSBoYW5kLWVkaXRlZCBhIHByb2plblxuICogbWFuYWdlZCBmaWxlIChwYWNrYWdlLmpzb24vcG9tLnhtbC8uZ2l0aHViL3dvcmtmbG93cy8qLnltbC8uLi4pIHdpdGhvdXRcbiAqIGdvaW5nIHRocm91Z2ggLnByb2plbnJjLlxuICovXG5leHBvcnQgZnVuY3Rpb24gZHJpZnRDaGVja1N0ZXBzKFxuICBwcm9qZW5Db21tYW5kID0gJ25weCBwcm9qZW4nLFxuKTogZ2l0aHViLndvcmtmbG93cy5Kb2JTdGVwW10ge1xuICByZXR1cm4gW1xuICAgIHtcbiAgICAgIG5hbWU6ICdDaGVjayBmb3IgcHJvamVuIGRyaWZ0JyxcbiAgICAgIHJ1bjogYCR7cHJvamVuQ29tbWFuZH1cXG5naXQgZGlmZiAtLWV4aXQtY29kZWAsXG4gICAgfSxcbiAgXTtcbn1cbiJdfQ==