Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,54 @@ pnpm dev # local preview
```bash
pnpm build:local # build + frontmatter validation (CI runs this too)
pnpm lint:slugcheck # permalink rules
pnpm lint:changelog # release notes entries (see below)
```

- Changed a permalink or moved a page? **Add the redirect in this PR**, in the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`, and list it on the redirect row of the PR checklist.
- Can't update `pt-br` yourself? Create the follow-up `i18n` issue and link it in the PR checklist.

### Changelog entries

The release notes and the changelog archive are records: an entry is never rewritten, so the
[changelog rules](../apps/docs/src/content/docs/en/pages/style-guide/content/changelog.mdx) of the
style guide apply in full to the entries you add. `pnpm lint:changelog` checks the changelog pages,
or the files you pass it.

Every entry, old or new, keeps an `anchor` that is unique on the page and starts with its date as a
slug, writes `label` and `anchor` in double quotes (the only form the page outline reads), and the
entries run newest first. An entry dated after October 22, 2026 also needs:

- the date as its `label`: `October 22, 2026` in English, `22 de outubro de 2026` in Portuguese;
- the date as its `anchor`: `october-22-2026`, `22-de-outubro-de-2026`. Another entry on the same
date adds its tag: `october-22-2026-azion-cli`;
- exactly one tag, from the list below: `tags={['Azion CLI']}`;
- `description="Version 4.25.0"` (`Versão 4.25.0` in Portuguese) only when the release has a version;
- a blank line after the opening tag and another before the closing tag;
- the closing link as its last paragraph, to a page in the same language:
`For more information, refer to [Azion CLI](/en/documentation/devtools/cli/).` or
`Para mais informações, consulte [Azion CLI](/pt-br/documentacao/devtools/cli/).`

The tags are the current names of the Platform Resources and products, plus the channels the release
notes report on. Older entries keep the names of their time.

- **Platform Resources and channels:** Azion API, Azion CLI, Azion Console, Azion MCP servers,
Terraform Provider, DevTools & Integrations, Marketplace, GraphQL API, Real-Time Metrics,
Applications, Firewall, Connectors, Workloads, Certificate Manager, Custom Pages, DDoS Protection,
Real-Time Purge, Copilot.
- **Build:** AI Inference, Application Accelerator, Cache, Durable Objects, Functions, Image
Processor, Live Ingest, LoRA Fine-Tune, Orchestrator.
- **Store:** KV Store, Object Storage, SQL Database.
- **Secure:** AI Gateway, Bot Manager, Edge DNS, Load Balancer, Network Shield, Origin Shield, Secure
Internet Access, WAF.
- **Observe:** Data Stream, Edge Pulse, Real-Time Events.

A release that needs a new tag adds it to this list and to `TAGS` in
`apps/docs/scripts/lint-changelog.mjs` in the same PR.

On a PR that changes a changelog page, the **Changelog entries** check runs the same script over the
pages the PR changes and annotates each finding on its line. It does not block the merge: you decide
whether to fix the entry there.

## The PR

- Title: `type(scope): imperative summary`, enforced by CI. **No ticket codes in the title**: the branch name and the Related issue field carry those, and squash makes titles permanent history.
Expand Down
7 changes: 7 additions & 0 deletions .github/GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,13 @@ what the check did *not* look at — and then fails if the count is higher than
`ci/baselines.json`. The report comes first and always, so the number reaches you whatever the check
decides; the check itself is one of the ratchets below.

**Changelog entries** is advisory, and it is not a ratchet. It checks the entries of the changelog
pages a PR changes: every entry keeps a unique, double-quoted anchor that matches its date and the
newest-first order, and a new entry follows the rest of the changelog rules. It annotates each finding on its
line and turns red when it finds one. It never blocks the merge: the author decides whether to fix
the entry in the same PR. It runs outside the CI gate and is not a required check, and it should
stay that way.

### Checks that ratchet

Five checks carry more debt than any one PR can clear, so they are frozen at a baseline in
Expand Down
70 changes: 70 additions & 0 deletions .github/workflows/changelog.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Checks the entries of the changelog pages a PR changes: every entry keeps a unique, double-quoted
# anchor that matches its date and the newest-first order, and an entry dated after the check was added follows
# the rest of the style guide's Changelog rules (label, one tag from a closed list, version, closing
# link). See apps/docs/scripts/lint-changelog.mjs for the rules and the closed tag list.
#
# Advisory on purpose. A finding turns this check red and annotates the lines, but the check is not
# a required status check and must not become one: the PR author decides whether to fix it. It is a
# workflow of its own, outside the CI gate, for that reason.
name: Changelog entries

on:
pull_request:
types: [opened, synchronize, reopened]
paths:
- 'apps/docs/src/content/docs/en/pages/main-menu/release-notes/**'
- 'apps/docs/src/content/docs/pt-br/pages/menu-principal/release-notes/**'
- 'apps/docs/src/content/docs/en/pages/changelog/**'
- 'apps/docs/src/content/docs/pt-br/pages/changelog/**'
- 'apps/docs/scripts/lint-changelog.mjs'
- '.github/workflows/changelog.yml'
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
changelog:
name: Changelog entries
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0

# On a PR, only the changelog pages it changes: a finding then belongs to a page the author
# touched. A PR that changes the script or this workflow, and a manual run, check every
# changelog page.
- name: Collect changed changelog pages
id: pages
if: github.event_name == 'pull_request'
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
# The diff goes to a file first: a failed diff must fail the step, not read as "no page
# changed". Only grep's "no match" is tolerated.
run: |
git diff --name-only --diff-filter=ACMR "$BASE_SHA...$HEAD_SHA" > changed.txt
grep -E '^apps/docs/src/content/docs/(en/pages/main-menu/release-notes|pt-br/pages/menu-principal/release-notes|en/pages/changelog|pt-br/pages/changelog)/.*\.mdx$' changed.txt > changed-pages.txt || true
if grep -qxE 'apps/docs/scripts/lint-changelog\.mjs|\.github/workflows/changelog\.yml' changed.txt; then
: > changed-pages.txt
fi
echo "count=$(wc -l < changed-pages.txt | tr -d ' ')" >> "$GITHUB_OUTPUT"

- uses: ./.github/actions/setup

- name: Lint the changelog entries
env:
EVENT: ${{ github.event_name }}
COUNT: ${{ steps.pages.outputs.count }}
run: |
if [ "$EVENT" = pull_request ] && [ "$COUNT" != 0 ]; then
tr '\n' '\0' < changed-pages.txt | xargs -0 node apps/docs/scripts/lint-changelog.mjs
else
node apps/docs/scripts/lint-changelog.mjs
fi
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ preferences.
- **Register a new page in a navigation tree** under `apps/docs/src/nav`, or nothing links to it
and it reaches no index.
- **Internal links are root-relative** (`/en/documentation/...`) and must resolve.
- **A new release notes entry follows the changelog rules:** the date as its `label` and
`anchor`, one tag from a closed list, and a closing link to a page in the same language. Run
`pnpm lint:changelog`; the rules and the tag list are in
[CONTRIBUTING.md](.github/CONTRIBUTING.md#changelog-entries). Never rewrite an older entry.
- Do not name competitors anywhere: not in pages, not in commit messages, not in pull request
descriptions.

Expand All @@ -57,6 +61,7 @@ pnpm build:local # build + frontmatter validation (CI runs this too)
pnpm lint:slugcheck # permalink rules
pnpm lint:navcheck # navigation trees
pnpm lint:links # internal links, without a build
pnpm lint:changelog # release notes entries: anchors, order, tags, closing link
pnpm format # prettier
```

Expand Down
1 change: 1 addition & 0 deletions apps/docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
"redirects:publish": "node ./cicd/massive-redirects/update-function-instances.mjs",
"lint:links": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-links.ts",
"lint:navcheck": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/lint-navcheck.ts",
"lint:changelog": "node ./scripts/lint-changelog.mjs",
"nav:url-map": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/url-map.ts",
"nav:migrate": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/migrate-permalinks.ts",
"nav:retarget": "tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/nav/retarget-links.ts",
Expand Down
Loading
Loading