Skip to content

chore(lint): check the changelog entries a PR adds - #2634

Merged
marcus-souza-azion merged 3 commits into
mainfrom
chore/mm-16259-changelog-lint
Nov 12, 2026
Merged

marcus-souza-azion merged 3 commits into
mainfrom
chore/mm-16259-changelog-lint

Conversation

@bruno-andrade-azion

@bruno-andrade-azion bruno-andrade-azion commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What & why

Related issue: MM-16259
Pages affected: none. This PR adds tooling (apps/docs/scripts/lint-changelog.mjs, .github/workflows/changelog.yml, the lint:changelog scripts) and documents it in AGENTS.md, .github/CONTRIBUTING.md and .github/GOVERNANCE.md.

The October docs review found that the release notes do not follow the style guide's changelog rules. The October 14 entry reused the October 9 anchor, so #october-9-2026 opened the wrong entry. A duplicate February 24 entry sat out of date order. Tags drift between Console and Azion Console, and between API, Azion APIs and Edge API. And 154 of the 158 en entries have no closing link. The rules are newer than most entries, and the log is append-only, so the fix is to check the entries people add from now on.

What the lint checks. pnpm lint:changelog [files] reads every DocUpdate entry on the four changelog pages: the release notes and the changelog archive, in en and pt-br. Entries inside code fences are skipped.

  • Every entry, old or new, is checked for what breaks the page for a reader today. Its anchor exists, is unique on the page, and starts with its date as a slug. label and anchor are in double quotes, the only form the page outline (src/util/docUpdateHeadings.ts) reads, so a single-quoted entry would drop out of it. The dates run newest first.
  • An entry dated after October 22, 2026 (the newest entry today) also gets the rest of the rules:
    • the label is October 22, 2026 in en or 22 de outubro de 2026 in pt-br, the form the pt-br style guide and numeros.mdx set;
    • the anchor is the date slug, or the date slug plus the tag slug for a second entry on the same date;
    • it has exactly one tag, from a closed list;
    • a description, when present, is Version x.y.z or Versão x.y.z;
    • it has notes: a self-closing <DocUpdate ... /> is reported on its own line;
    • a blank line follows the opening tag and another precedes the closing tag;
    • the last paragraph is the closing link (For more information, refer to … or Para mais informações, consulte …) to a root-relative page in the same language.

Older entries are records, so none of them gets these rules. A label that cannot be read as a date is reported only above every older entry, where new entries go.

The closed tag list comes from the current product catalog: the Platform Resources (with the Azion prefix the release notes already use for API, CLI and Console), the products in Build, Store, Secure and Observe, and the channels the release notes report on (Marketplace, DevTools & Integrations, Azion MCP servers, GraphQL API, Real-Time Metrics). It includes the nested Platform Resources, DDoS Protection among them. CONTRIBUTING.md lists it. A tag the pages used before, or an earlier product name, gets a suggestion: Console → Azion Console, Edge Functions → Functions, Digital Certificates → Certificate Manager, and the pt-br forms DevTools & Integrações → DevTools & Integrations and Vector Search do Edge SQL → SQL Database.

A file passed to pnpm lint:changelog that does not exist, or is not a .md or .mdx file, stops the run with exit code 2, so a mistyped path never reads as a pass.

How it runs. A new Changelog entries workflow runs on PRs that touch the changelog pages, the script, or the workflow. It lints the changelog pages the PR changes, or all four when the PR changes the script or the workflow, even alongside a page, so a script change is always tested against every page. It annotates each finding on its line and writes a table to the run Summary. A manual run (workflow_dispatch) checks every changelog page.

The workflow is advisory, like Code blocks in #2623. A finding turns the check red, but it is not a required status check, so the PR author decides whether to fix the entry. The workflow stays out of the CI gate: this PR does not touch its workflow, scripts or baselines.

What it finds today. On main, with #2572 merged, 0 findings in 443 entries. #2624 fixes the Janeeiro, 2022 label typo in pt-br but keeps the janeeiro-2022 anchor, which turns into 1 finding once it merges; no page links that anchor. No page changes in this PR, so that fix stays in #2624.

How I checked it

  • Fixtures in en and pt-br with 31 entries: each rule fails on its own planted case, including three historic entries planted to fail the anchor and order checks. The valid entries and the other historic entries report nothing (27 findings, all expected).
  • I added a well-formed entry to copies of both real pages and a sloppy entry to the en copy. The well-formed entries passed, and the sloppy one got the order, tag and closing-link findings.
  • main, docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry #2572's branch and i18n(pt-br): resync the drifted release notes, punctuation, and Edge Services pairs #2624's branch give the counts above.
  • A full run takes about 1 second.
  • I simulated the workflow steps locally with docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry #2572's diff: changed-page collection, the xargs call, the annotations, the step summary, and the non-zero exit on findings.
  • eslint --max-warnings 0 and prettier --check pass on the changed files, and the workflow YAML parses.
  • pnpm build:local passes: 2,092 pages built, and the frontmatter check runs clean.
  • Review follow-up, after the rebase on main: a second fixture set with a single-quoted entry, a self-closing entry, a DDoS Protection entry and the three new aliases gives exactly the 6 expected findings; the DDoS Protection entry passes. A missing path, a directory and a .txt file each exit 2. The four real pages give 0 findings. The changed-pages step, run locally on four changed.txt cases, checks one page for a page-only PR and all four when the script or the workflow changes. eslint --max-warnings 0 and prettier --check pass, and the workflow YAML parses.

Not verified: the changed-pages path on GitHub, where a PR touches a changelog page. I simulated it only locally. workflow_dispatch becomes available only once the file is on main.

Follow-ups, not in this PR

Type of change

  • 🆕 New content (feat)
  • 🩹 Fix (fix) — typo, broken link, wrong information
  • ♻️ Content update (docs) — rewrite, expansion, upkeep
  • 🌐 Translation sync (i18n)
  • 🏗️ Platform / structure (refactor / chore) — reviewed by UXE, no content mixed in

Author checklist

  • PR title follows type(scope): summary (see GOVERNANCE.md §4)
  • Frontmatter complete: title, description, meta_tags, namespace, permalink, last_reviewed — no page is added or changed
  • No legacy "edge-" product names in the copy — the only legacy names are the aliases in the script that map old tags to current ones
  • How-to/tutorial content includes at least one runnable, copy-paste-tested code block — no how-to or tutorial is changed
  • Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
  • Internal links are relative and resolve locally — the links added, in AGENTS.md and CONTRIBUTING.md, point to .github/CONTRIBUTING.md#changelog-entries and to the style guide's changelog.mdx
  • If any permalink changed or page moved: redirect added in this PR — no permalink changed and no page moved
  • i18n: pt-br updated in this PR or follow-up i18n issue created: — no page text changed; the lint covers the en and pt-br changelog pages alike
  • I ran pnpm build:local (build + frontmatter check) without errors — on the first two commits; the review follow-up changes only the lint script, the workflow and .github docs, which the build does not read

egermano and others added 3 commits November 12, 2026 12:12
Add lint:changelog, which reads the DocUpdate entries of the release
notes and the changelog archive in en and pt-br. Every entry keeps a
unique anchor that starts with its date and the newest-first order. An
entry dated after October 22, 2026 also follows the rest of the style
guide's changelog rules: the label form, the date anchor, one tag from a
closed list, the version line, the blank lines around the notes, and a
closing link to a page in the same language. Older entries are records
and are never rewritten, so they get only the first two checks.

A new advisory Changelog entries workflow runs it on PRs that touch the
changelog pages. It annotates findings but is not a required check, and
it stays out of the CI gate.
- Flag a label or anchor outside double quotes: the page outline reads only
  double-quoted values, so the entry drops out of it.
- Flag a self-closing DocUpdate instead of reporting its closing link on the
  entry above.
- Exit with an error when a file argument does not exist, instead of checking
  nothing and passing.
- Check every changelog page when a PR changes the script or the workflow,
  even if it also changes a page.
- Add DDoS Protection to the closed tag list, and suggest Certificate Manager,
  DevTools & Integrations, and SQL Database for the tags the pages used before.
@marcus-souza-azion
marcus-souza-azion force-pushed the chore/mm-16259-changelog-lint branch from 793658f to 811d845 Compare November 12, 2026 15:19
@marcus-souza-azion
marcus-souza-azion merged commit 186b17e into main Nov 12, 2026
10 checks passed
@marcus-souza-azion
marcus-souza-azion deleted the chore/mm-16259-changelog-lint branch November 12, 2026 15:23
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (39 commits)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  docs(observe): fix dataset name, Data Stream filter, and Grafana Data path (#2573)
  fix(fundamentals): rewrite the Load Balancer steps in minimize-downtime from the reference (#2578)
  i18n(pt-br): label unlabelled asides and fix label casing (#2622)
  fix(links): point pt-br links to their existing pt-br pages (#2620)
  i18n(pt-br): resync the drifted release notes, punctuation, and Edge Services pairs (#2624)
  i18n(pt-br): pair three pages with their English versions by namespace (#2625)
  docs(style-guide): adopt the jsonl tag for JSON Lines samples (#2642)
  chore(lint): check the changelog entries a PR adds (#2634)
  [NO-ISSUE] ci: replace technote-space/assign-author (SO-5131) (#2591)
  fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags (#2629)
  docs(style-guide): drop the nonexistent GlossaryFilter from the glossary template (#2577)
  docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry (#2572)
  fix(orchestrator): fix broken bind and create-service API samples (#2574)
  docs(readability): split the long sentences in the Runtime, CLI, Reference, and KV Store pages (#2635)
  chore(nav): count only visible rows toward the navcheck soft max (#2640)
  docs(nav): triage the pages outside the navigation (#2593)
  fix(guides): match the QStash variable and the Functions usage response to the code (#2571)
  feat(nav): give every breadcrumb crumb a page and make CLI commands runnable (#2636)
  fix(cli): drop azion update workload-deployment, which the CLI does not expose (#2639)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/store/sql-database/glossary.mdx
#	apps/docs/src/content/docs/pt-br/pages/store/sql-database/glossario.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (53 commits)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  docs(observe): fix dataset name, Data Stream filter, and Grafana Data path (#2573)
  fix(fundamentals): rewrite the Load Balancer steps in minimize-downtime from the reference (#2578)
  i18n(pt-br): label unlabelled asides and fix label casing (#2622)
  fix(links): point pt-br links to their existing pt-br pages (#2620)
  i18n(pt-br): resync the drifted release notes, punctuation, and Edge Services pairs (#2624)
  i18n(pt-br): pair three pages with their English versions by namespace (#2625)
  docs(style-guide): adopt the jsonl tag for JSON Lines samples (#2642)
  chore(lint): check the changelog entries a PR adds (#2634)
  [NO-ISSUE] ci: replace technote-space/assign-author (SO-5131) (#2591)
  fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags (#2629)
  docs(style-guide): drop the nonexistent GlossaryFilter from the glossary template (#2577)
  docs(release-notes): fix the October 14 anchor and merge the duplicate February 24 entry (#2572)
  fix(orchestrator): fix broken bind and create-service API samples (#2574)
  docs(readability): split the long sentences in the Runtime, CLI, Reference, and KV Store pages (#2635)
  chore(nav): count only visible rows toward the navcheck soft max (#2640)
  docs(nav): triage the pages outside the navigation (#2593)
  fix(guides): match the QStash variable and the Functions usage response to the code (#2571)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/personal-tokens.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/reference/services/support/http-error-status-codes.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/personal-tokens.mdx
bruno-andrade-azion pushed a commit that referenced this pull request Nov 12, 2026
* origin/main: (48 commits)
  docs(templates): list the Astro templates that only the showcase covered (#2595)
  docs(orchestrator): consolidate duplicate guides and write How it works (#2588)
  docs(secure): retire the pre-Workloads security journey and guide pages (#2586)
  docs(applications): Run Function needs only Functions; fix WEBP and CORS prerequisites (#2580)
  docs(fundamentals): apply the reader review and the style guide to the Fundamentals pages (#2558)
  fix(observe): name the query editor list instead of its position in the Grafana guides (#2643)
  docs(templates): migrate the legacy template guides to the current guide pattern (#2597)
  docs(style-guide): standardize Azion Console click paths (#2596)
  docs(store): name the SQL and Storage libraries by their scoped packages (#2575)
  fix(terminology): replace desempenho and aplicativo in pt-br pages (#2621)
  docs(observe): fix dataset name, Data Stream filter, and Grafana Data path (#2573)
  fix(fundamentals): rewrite the Load Balancer steps in minimize-downtime from the reference (#2578)
  i18n(pt-br): label unlabelled asides and fix label casing (#2622)
  fix(links): point pt-br links to their existing pt-br pages (#2620)
  i18n(pt-br): resync the drifted release notes, punctuation, and Edge Services pairs (#2624)
  i18n(pt-br): pair three pages with their English versions by namespace (#2625)
  docs(style-guide): adopt the jsonl tag for JSON Lines samples (#2642)
  chore(lint): check the changelog entries a PR adds (#2634)
  [NO-ISSUE] ci: replace technote-space/assign-author (SO-5131) (#2591)
  fix(structure): tag bare code fences, fix heading skips, add pt-br meta_tags (#2629)
  ...

# Conflicts:
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/billing.mdx
#	apps/docs/src/content/docs/en/pages/main-menu/reference/accounts/teams-permissions.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/faturamento.mdx
#	apps/docs/src/content/docs/pt-br/pages/menu-principal/referencia/contas/teams-permissions.mdx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants