From da2926318842c5fd80d4c945c36c2e858ca97b0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Wed, 11 Nov 2026 16:33:59 +0100 Subject: [PATCH] [tooling] Changelog: kind/internal and kind/epic always exclude an issue, even with a category label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An issue with kind/internal or kind/epic is now out of scope for the generated changelog whatever other kind/* labels it has, instead of only when no category label is present. Excluded issues are still listed in the report and still count as a closing issue. Closes #308 Signed-off-by: Jesus Manuel Piñeiro Cid --- .github/scripts/changelog-from-prs.mjs | 12 ++++----- .github/scripts/changelog-from-prs.test.mjs | 26 +++++++++++++++---- .../workflows/docs/code-changelog-check.md | 2 +- ...e-npm_node-publish-release-and-snapshot.md | 2 +- .opencode/skills/changelog/SKILL.md | 4 +-- AGENTS.md | 2 +- CONTRIBUTING.md | 5 ++-- .../design.md | 2 +- .../proposal.md | 2 +- .../specs/changelog-generation/spec.md | 6 ++--- .../tasks.md | 2 +- 11 files changed, 41 insertions(+), 24 deletions(-) diff --git a/.github/scripts/changelog-from-prs.mjs b/.github/scripts/changelog-from-prs.mjs index 44d65a72..e44a06c8 100644 --- a/.github/scripts/changelog-from-prs.mjs +++ b/.github/scripts/changelog-from-prs.mjs @@ -68,10 +68,10 @@ export const SECTION_RULES = [ ]; export const FALLBACK_SECTION = 'Changed'; -// Issues with only these labels (no SECTION_RULES category) are out of scope -// for the changelog: `kind/epic` is a size flag and `kind/internal` means no -// user-facing effect. A real category label wins over them. They are listed -// in the report instead of the changelog, never dropped silently. +// An issue with either of these labels is out of scope for the changelog, +// whatever other `kind/*` labels it has: `kind/epic` is a size flag and +// `kind/internal` means no user-facing effect. Such issues are listed in the +// report instead of the changelog, never dropped silently. export const EXCLUDED_LABELS = ['kind/internal', 'kind/epic']; // Keep a Changelog order, used only to place a section that does not exist yet. @@ -158,12 +158,12 @@ export function buildEntries(prs, { repo }) { continue; } seen.add(key); - const { section, guessed } = sectionFor(issue.labels); - const outOfScope = guessed && issue.labels.find((label) => EXCLUDED_LABELS.includes(label.toLowerCase())); + const outOfScope = issue.labels.find((label) => EXCLUDED_LABELS.includes(label.toLowerCase())); if (outOfScope) { excluded.push({ ref: issueRef(issue, repo), pr: pr.number, label: outOfScope }); continue; } + const { section, guessed } = sectionFor(issue.labels); if (guessed) { warnings.push( `Section guessed for ${issueRef(issue, repo)}: the issue has none of the labels ` + diff --git a/.github/scripts/changelog-from-prs.test.mjs b/.github/scripts/changelog-from-prs.test.mjs index 744711c9..d0bb7c5e 100644 --- a/.github/scripts/changelog-from-prs.test.mjs +++ b/.github/scripts/changelog-from-prs.test.mjs @@ -149,13 +149,29 @@ describe('buildEntries', () => { assert.deepEqual(warnings, []); }); - it('a real category wins over kind/internal and kind/epic', () => { - const { entries, excluded } = buildEntries( - [pr(1, [issue(50, 'Big', ['kind/epic', 'kind/enhancement']), issue(51, 'Odd', ['kind/internal', 'kind/bug'])])], + it('kind/internal and kind/epic exclude an issue even with a real category', () => { + const { entries, excluded, warnings } = buildEntries( + [ + pr(1, [ + issue(50, 'Big', ['kind/epic', 'kind/enhancement']), + issue(51, 'Odd', ['kind/bug', 'kind/internal']), + issue(52, 'Real', ['kind/bug']), + ]), + ], { repo: REPO } ); - assert.deepEqual(entries.map((entry) => [entry.ref, entry.section]), [['#50', 'Added'], ['#51', 'Fixed']]); - assert.deepEqual(excluded, []); + assert.deepEqual(entries.map((entry) => [entry.ref, entry.section]), [['#52', 'Fixed']]); + assert.deepEqual(excluded, [ + { ref: '#50', pr: 1, label: 'kind/epic' }, + { ref: '#51', pr: 1, label: 'kind/internal' }, + ]); + assert.deepEqual(warnings, []); + }); + + it('matches the excluded labels case-insensitively', () => { + const { entries, excluded } = buildEntries([pr(1, [issue(53, 'Odd', ['Kind/Internal', 'kind/bug'])])], { repo: REPO }); + assert.deepEqual(entries, []); + assert.deepEqual(excluded.map((item) => item.ref), ['#53']); }); it('ignores skip-changelog: the issue labels alone decide', () => { diff --git a/.github/workflows/docs/code-changelog-check.md b/.github/workflows/docs/code-changelog-check.md index cc81b551..d39e256f 100644 --- a/.github/workflows/docs/code-changelog-check.md +++ b/.github/workflows/docs/code-changelog-check.md @@ -15,7 +15,7 @@ Any pull request to `main` or `main-*` that is `opened`, `synchronize`d, `reopen - The link is a GitHub closing reference: a closing keyword in the PR body (`Closes #N`) or the Development sidebar. A plain `#N` mention is not one. GitHub only reads closing keywords on PRs to the default branch, so PRs to `main-*` need the sidebar. - A maintainer can waive the rule with the `skip-release` label, which also skips the release on merge. The issues such a PR does close still get entries in the next release. - Dependabot PRs are exempt. -- Issues labelled only `kind/internal` or `kind/epic` (no `kind/*` category) count as a link but get no entry, and an issue already listed in an earlier release is not listed again. Both are shown in the report. `skip-changelog` has no effect. +- Issues labelled `kind/internal` or `kind/epic`, even together with a `kind/*` category, count as a link but get no entry, and an issue already listed in an earlier release is not listed again. Both are shown in the report. `skip-changelog` has no effect. - The check is warn-only for now: `CHANGELOG_LINK_ENFORCE` is `'false'`. Setting it to `'true'` (a follow-up PR, once a release has run end to end) makes a PR with no linked issue and no bypass fail. ## Jobs diff --git a/.github/workflows/docs/code-npm_node-publish-release-and-snapshot.md b/.github/workflows/docs/code-npm_node-publish-release-and-snapshot.md index a7dfaa7f..3a3693d8 100644 --- a/.github/workflows/docs/code-npm_node-publish-release-and-snapshot.md +++ b/.github/workflows/docs/code-npm_node-publish-release-and-snapshot.md @@ -80,7 +80,7 @@ Permissions are scoped at the job level following the principle of least privile - Install dependencies and run `lint`, `typecheck`, `format:check`, and `test` before releasing. - Determine the release type from labels. - Prepare committer information and configure GPG signing (gpg-agent with loopback-pinentry and preset-passphrase). - - Generate `[Unreleased]` in `CHANGELOG.md` from the issues closed by the PRs merged since the last numeric tag (`.github/scripts/changelog-from-prs.mjs --branch `); issues labelled only `kind/internal`/`kind/epic`, or already listed in an earlier release, are reported instead of written. Any error fails the job before the bump, the commit and the tag. + - Generate `[Unreleased]` in `CHANGELOG.md` from the issues closed by the PRs merged since the last numeric tag (`.github/scripts/changelog-from-prs.mjs --branch `); issues labelled `kind/internal`/`kind/epic` (alone or with another label), or already listed in an earlier release, are reported instead of written. Any error fails the job before the bump, the commit and the tag. - Update CHANGELOG.md and calculate next version using `release-flow/keep-a-changelog-action`. - Bump every package to the released version (same `npm run version:release` + `npm run release:prepare` pair as the snapshot job). - Build (`pnpm build`) and locate the `ui-bundle` release artifact. diff --git a/.opencode/skills/changelog/SKILL.md b/.opencode/skills/changelog/SKILL.md index e553c6df..16440ac5 100644 --- a/.opencode/skills/changelog/SKILL.md +++ b/.opencode/skills/changelog/SKILL.md @@ -61,10 +61,10 @@ released section is not listed again (it is reported as a warning). Entries up t | `kind/documentation` | `### Documentation` | | `kind/deprecated` | `### Deprecated` | | `kind/removed` | `### Removed` | -| `kind/internal` / `kind/epic` alone | **no entry** (listed in the report as out of scope, never dropped silently) | +| `kind/internal` / `kind/epic` (alone or with any other label) | **no entry** (listed in the report as out of scope, never dropped silently) | | none of the above | `### Changed`, with a "section guessed" warning — fix the label | -A real category label wins over `kind/internal`/`kind/epic`; `kind/epic` is a size flag +`kind/internal`/`kind/epic` always win over a real category label: an issue with either is excluded whatever else it carries. `kind/epic` is a size flag only. Empty sections are omitted. ## Where it runs diff --git a/AGENTS.md b/AGENTS.md index 20a398fa..569c00d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -118,7 +118,7 @@ npx skills@latest add InditexTech/docouture --all that merged PRs close (`.github/scripts/changelog-from-prs.mjs`). Do not add entries by hand. Every PR must close an issue (`Closes #N` or the Development sidebar; a plain `#N` does not count) — the entry is `- [#N](issue URL) `, in the section given by -the issue's `kind/*` label. `kind/internal`/`kind/epic` alone means no entry. `skip-release` +the issue's `kind/*` label. `kind/internal`/`kind/epic` always means no entry, even with another `kind/*` label. `skip-release` (and Dependabot) exempt a PR from needing an issue but do **not** stop an issue it does close from getting its entry. `skip-changelog` no longer exists and has no effect. To change an entry's wording, edit the issue title. Full rules: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 41cea27a..f9c08143 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,8 +97,9 @@ logo is ever redesigned, update both locations. Security, `kind/bug` → Fixed, `kind/enhancement` → Added, `kind/documentation` → Documentation, `kind/deprecated` → Deprecated, `kind/removed` → Removed, anything else → Changed (flagged as guessed). - - Issues labelled only `kind/internal` or `kind/epic` get no entry, and an issue already - listed in an earlier release is not listed again. Both are shown in the report. + - Issues labelled `kind/internal` or `kind/epic` get no entry, even with another `kind/*` + label, and an issue already listed in an earlier release is not listed again. Both are + shown in the report. - To change the wording of an entry, edit the issue title; to change its section, change the issue labels. - Releases up to 1.3.2 keep their hand-written changelog sections as history. diff --git a/openspec/changes/generate-changelog-from-closing-issues/design.md b/openspec/changes/generate-changelog-from-closing-issues/design.md index 3eb83d6e..c4c7c78d 100644 --- a/openspec/changes/generate-changelog-from-closing-issues/design.md +++ b/openspec/changes/generate-changelog-from-closing-issues/design.md @@ -25,7 +25,7 @@ See proposal.md. Today `code-npm_node-pr-verify.yml` gates on a hand-edited `[Un - **Warn-only rollout via `CHANGELOG_LINK_ENFORCE`**, flipped by a follow-up PR after one end-to-end release. - **Generate step placed before `keep-a-changelog bump` in the release job only**; `fail-on-empty-release-notes: false` is already set, verify an empty `[Unreleased]` is tolerated. - **Plain Node (.mjs), GraphQL via `fetch` with retry+backoff on 5xx/429/rate limits**, tests with `node --test` and an injected `fetch`, matching existing `.github/scripts` style. Needs only `GITHUB_TOKEN`, no `gh`. -- **Exclusion rule differs from weavejs:** weavejs drops any issue labelled `internal`; here `kind/internal`/`kind/epic` exclude an issue only when no real `kind/*` category is present, preserving the convention that a real category wins. +- **Exclusion rule differs from weavejs:** weavejs drops any issue labelled `internal`; here `kind/internal`/`kind/epic` exclude an issue whatever other `kind/*` labels it has (#308), so the labels mean the same thing on every issue. - **Release preview in two passes** (`--to HEAD^1 --branch `, then `--pr N`) instead of one `--include-pr`, so the preview includes entries pending from `skip-release` PRs and the PR's own report. ## Risks / Trade-offs diff --git a/openspec/changes/generate-changelog-from-closing-issues/proposal.md b/openspec/changes/generate-changelog-from-closing-issues/proposal.md index 7196ca93..e05eac1c 100644 --- a/openspec/changes/generate-changelog-from-closing-issues/proposal.md +++ b/openspec/changes/generate-changelog-from-closing-issues/proposal.md @@ -7,7 +7,7 @@ Every PR touching `code/**` must hand-edit `[Unreleased]` in `code/CHANGELOG.md` ## What Changes - Port `.github/scripts/changelog-from-prs.mjs` (and its tests) from InditexTech/weavejs#1252/#1286/#1288, adapted to this repo's `kind/*` labels and a Documentation section. Two modes: range mode (last numeric tag..`--to`, restricted to PRs merged into `--branch`, writes `[Unreleased]`) and `--pr N` mode (read-only preview/check), plus `--dry-run` (compares with the hand-written `[--to]` section), `--report`, `--enforce` and `--wrap-titles`. -- Entries are generated from each merged PR's closing issues (GitHub `closingIssuesReferences`): `- [#N](.../issues/N) `, deduplicated by issue number. Section is chosen from the issue's `kind/*` label (first match wins); no label falls back to Changed with a warning; `kind/internal`/`kind/epic` alone produce no entry but are listed in the report. +- Entries are generated from each merged PR's closing issues (GitHub `closingIssuesReferences`): `- [#N](.../issues/N) `, deduplicated by issue number. Section is chosen from the issue's `kind/*` label (first match wins); no label falls back to Changed with a warning; `kind/internal`/`kind/epic` produce no entry, even with another `kind/*` label, but are listed in the report. - Every PR must close an issue (closing keyword or Development sidebar). Bypass: the `skip-release` label; Dependabot is exempt. A bypassed PR with no issue gets no entry; a `skip-release` PR that closes an issue still gets its entry. - **BREAKING (contributor workflow)**: contributors no longer edit `code/CHANGELOG.md`. The `skip-changelog` label is dropped entirely and has no effect; the issue's labels alone decide whether and where an entry appears. - The script skips an issue already listed in an earlier released section (with a warning), verifies before writing that only `[Unreleased]` changes and each added entry appears exactly once, and fails instead of silently truncating when a GitHub pagination limit is hit. diff --git a/openspec/changes/generate-changelog-from-closing-issues/specs/changelog-generation/spec.md b/openspec/changes/generate-changelog-from-closing-issues/specs/changelog-generation/spec.md index 1a05eb2c..4d93bcd4 100644 --- a/openspec/changes/generate-changelog-from-closing-issues/specs/changelog-generation/spec.md +++ b/openspec/changes/generate-changelog-from-closing-issues/specs/changelog-generation/spec.md @@ -25,12 +25,12 @@ The system SHALL place each entry in the section chosen by the first matching is - **THEN** its entry is placed under Changed and a "section guessed" warning is reported #### Scenario: Internal issue -- **WHEN** an issue carries only `kind/internal` and/or `kind/epic` +- **WHEN** an issue carries `kind/internal` and/or `kind/epic` - **THEN** no entry is written and the issue is listed in the report as out of scope -#### Scenario: Real category wins +#### Scenario: Internal wins over a real category - **WHEN** an issue carries `kind/epic` or `kind/internal` together with a real category label -- **THEN** the entry is written in the section of the real category +- **THEN** no entry is written and the issue is listed in the report as out of scope ### Requirement: Entry title is the issue title The system SHALL use the issue title verbatim, normalising only non-breaking and invisible whitespace. diff --git a/openspec/changes/generate-changelog-from-closing-issues/tasks.md b/openspec/changes/generate-changelog-from-closing-issues/tasks.md index 5a3c53aa..c9389976 100644 --- a/openspec/changes/generate-changelog-from-closing-issues/tasks.md +++ b/openspec/changes/generate-changelog-from-closing-issues/tasks.md @@ -2,7 +2,7 @@ ## 1. Generator script -- [x] 1.1 Port `changelog-from-prs.mjs` and `changelog-from-prs.test.mjs` from `/Users/jesusmpc/Inditex/weavejs/.github/scripts/` to `.github/scripts/`, adapted to `kind/*` labels, a Documentation section and the "real category wins over `kind/internal`/`kind/epic`" rule; verify `node --test .github/scripts/changelog-from-prs.test.mjs` passes (36 tests) +- [x] 1.1 Port `changelog-from-prs.mjs` and `changelog-from-prs.test.mjs` from `/Users/jesusmpc/Inditex/weavejs/.github/scripts/` to `.github/scripts/`, adapted to `kind/*` labels, a Documentation section and the "`kind/internal`/`kind/epic` always exclude" rule (#308); verify `node --test .github/scripts/changelog-from-prs.test.mjs` passes (36 tests) - [x] 1.2 Export `normalizeInvisibleWhitespace` from `sanitize-changelog.mjs`; verify the NBSP title test passes and `sanitize-changelog.mjs --check code/CHANGELOG.md` stays clean on a generated copy - [x] 1.3 Verify `--dry-run --from 1.2.0 --to 1.3.0` and `--from 1.3.1 --to 1.3.2` against the hand-written sections (differences are only PR-vs-issue links, serializer escaping and docs-only issues), `--pr 297` output, idempotent write on a copy of the changelog, and non-zero exit on a bad ref / missing token - [x] 1.4 Verify generated entries match the bullet format `changelog-pages.js` parses (`^- [#N](url)`)