From ba03aceb452cc8638cf12c988b86a96a276a6a75 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Wed, 7 Oct 2026 15:13:54 +0200 Subject: [PATCH 01/18] Use the release PR's current section names in the changelog skill write-changelog-item still pointed to Release Notes Required and Memgraph PRs Docs Needed. It now uses the Docs Integration Tracking sections that new-release-branch creates and check-release-milestone reads. --- skills/check-release-milestone/SKILL.md | 4 ++-- skills/write-changelog-item/SKILL.md | 21 +++++++++++++-------- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/skills/check-release-milestone/SKILL.md b/skills/check-release-milestone/SKILL.md index 7f289ad9a..0cf5cff33 100644 --- a/skills/check-release-milestone/SKILL.md +++ b/skills/check-release-milestone/SKILL.md @@ -87,8 +87,8 @@ Rules for this format: 4. **Changelog check** - Open `pages/release-notes.mdx` and locate the section for the new release (e.g. `### Memgraph v3.9.0`). - - For each PR in **Release Notes Required**, confirm it appears in that section (e.g. as `[#NNNN](https://github.com/memgraph/memgraph/pull/NNNN)` or equivalent). - - Optionally cross-check the memgraph milestone: merged PRs with user-visible work (e.g. **Docs needed**, **Docs - changelog only**) that are absent from that release section should also be treated as **missing from changelog**, even if they were never added to **Release Notes Required** on the docs PR. + - For each PR in **Changelog**, confirm it appears in that section (e.g. as `[#NNNN](https://github.com/memgraph/memgraph/pull/NNNN)` or equivalent). + - Optionally cross-check the memgraph milestone: merged PRs with user-visible work (e.g. **Docs needed**, **Docs - changelog only**) that are absent from that release section should also be treated as **missing from changelog**, even if they were never added to **Changelog** on the docs PR. - List any **missing from changelog** with PR numbers (and titles if known). **If anything is missing from the changelog:** follow **`skills/write-changelog-item/SKILL.md`** end-to-end for each gap. That skill defines how to write the item (user-friendly / user-centric impact, not engineering work; markdown; PR link; breaking vs non-breaking; whether the change is release-notes-only or must also be propagated into the docs), where to place it in `pages/release-notes.mdx` (correct section, ascending PR # within the section), and requires updating `pages/release-notes.mdx` plus keeping the open documentation release PR description aligned. When updating the docs PR body, use the **Docs Integration Tracking** checklist format described in the Assumptions section — tick `[x]` on the relevant **Changelog** line and, if the PR is also "Docs needed", on the **Docs needed** line once a doc PR exists. Do not use a different format or skip the release PR body update. diff --git a/skills/write-changelog-item/SKILL.md b/skills/write-changelog-item/SKILL.md index 59c111438..2b14e03f1 100644 --- a/skills/write-changelog-item/SKILL.md +++ b/skills/write-changelog-item/SKILL.md @@ -118,12 +118,17 @@ description of the open documentation release PR (e.g. everything integrated in the release. 1. Fetch the current PR body via `gh api`. -2. Add the memgraph PR to the **Release Notes Required** section if it is not - already listed. Use the same format as the existing entries: +2. In the **Docs Integration Tracking** section, add the memgraph PR to + **Changelog (all PRs requiring a changelog entry)** if it is not already + listed, or tick its line. Use the format the section already uses: `- [x] https://github.com/memgraph/memgraph/pull/XXXX @author` - Append the new entry at the end of the list (before the blank line / TODO). -3. If the memgraph PR has the **"Docs needed"** label and a corresponding - documentation PR exists, also add it to the **Memgraph PRs Docs Needed** - section using the existing format: - `- [x] https://github.com/memgraph/memgraph/pull/XXXX -> https://github.com/memgraph/documentation/pull/YYYY @author` -4. Push the updated body back via `gh api ... -X PATCH -F "body=@file"`. + Keep the list in ascending PR number order. +3. If the memgraph PR has the **"Docs needed"** label, also make sure it is + listed under **Docs needed (Memgraph PR → Docs PR)**: + `- [x] https://github.com/memgraph/memgraph/pull/XXXX → https://github.com/memgraph/documentation/pull/YYYY @author` + Tick it only when the docs PR exists; otherwise leave it unticked with + `→ no doc PR yet`. +4. If the memgraph PR has the `breaking` label, make sure it is listed under + **Breaking changes PRs**: + `- [x] https://github.com/memgraph/memgraph/pull/XXXX — short title @author` +5. Push the updated body back via `gh api ... -X PATCH -F "body=@file"`. From a399cb1f4832b4d4ed5a151751dba7dc16a0a4e3 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Wed, 7 Oct 2026 15:14:19 +0200 Subject: [PATCH 02/18] Point the release grammar check at the writing skill's naming rules The MAIN/REPLICA rule now lives in write-docs-page's tone.md, so engineers writing docs follow it too. Step 6 points there instead of keeping its own copy. --- skills/check-release-milestone/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/check-release-milestone/SKILL.md b/skills/check-release-milestone/SKILL.md index 0cf5cff33..67fe3263a 100644 --- a/skills/check-release-milestone/SKILL.md +++ b/skills/check-release-milestone/SKILL.md @@ -108,8 +108,8 @@ Rules for this format: - **Missing articles** ("creation of init container" → "creation of **an** init container"). - **Wrong word forms** ("set-up" used as a verb → "set up"; "additionally to" → "in addition to"). - **Stray punctuation** (accidental periods, double spaces in non-trailing positions). - - **Capitalization** - if the text is dealing with high availability and mentioning MAIN and REPLICA instances, use capital letters. When using in plural, write MAINs and REPLICAs. - + - **Names and terms** that don't follow the writing rules engineers use, in the `write-docs-page` skill's `references/tone.md` (`memgraph/infra`, `agents/docs/skills/write-docs-page`): product names, MAIN and REPLICA in capitals (MAINs and REPLICAs in the plural), American English. Add a new naming rule there, not here, so docs written with the skill follow it too. + - Do **not** rewrite for style or restructure paragraphs. Only fix clear errors: misspellings, missing/wrong articles, broken grammar, and wrong word forms. - Apply fixes directly, then list what was changed in the report. From ceece14d056f955cdcf1c87f43e004e341c98d72 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Wed, 7 Oct 2026 15:22:52 +0200 Subject: [PATCH 03/18] Link each release note to the docs page for its change write-changelog-item now links the docs page (and section) for a change in its entry, and check-release-milestone checks that every Docs needed entry has that link. --- skills/check-release-milestone/SKILL.md | 2 ++ skills/write-changelog-item/SKILL.md | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/skills/check-release-milestone/SKILL.md b/skills/check-release-milestone/SKILL.md index 67fe3263a..b97393407 100644 --- a/skills/check-release-milestone/SKILL.md +++ b/skills/check-release-milestone/SKILL.md @@ -88,6 +88,7 @@ Rules for this format: 4. **Changelog check** - Open `pages/release-notes.mdx` and locate the section for the new release (e.g. `### Memgraph v3.9.0`). - For each PR in **Changelog**, confirm it appears in that section (e.g. as `[#NNNN](https://github.com/memgraph/memgraph/pull/NNNN)` or equivalent). + - For each PR in **Docs needed**, confirm its entry links to the docs page for the change (a root-relative link such as `/querying/text-search#create-text-index`). The docs CI checks that the page and section exist; this step checks that the link is there. List entries without one as **missing docs link** and add the link. - Optionally cross-check the memgraph milestone: merged PRs with user-visible work (e.g. **Docs needed**, **Docs - changelog only**) that are absent from that release section should also be treated as **missing from changelog**, even if they were never added to **Changelog** on the docs PR. - List any **missing from changelog** with PR numbers (and titles if known). @@ -131,6 +132,7 @@ Rules for this format: - Sort every PR list in the report by PR number ascending (smallest → largest). - **Docs label issues:** list every merged PR with a missing or questionable label, the recommended label, and a one-line reason. The canvas from step 1 serves as the primary deliverable for this section. - **Not in changelog:** summarize all gaps (PR numbers and titles). When remediating, apply the **one item at a time** rule from step 4. For each gap, state that remediation follows **`write_changelog_item`** per `skills/write-changelog-item/SKILL.md` (unless the user asked for report-only). Include PRs found only via milestone cross-check. + - **Missing docs links:** entries for **Docs needed** PRs that did not link their docs page, with the link added. - **Docs page missing:** list merged memgraph PRs labeled "Docs needed" with no doc PR on the tracking list; briefly note what's missing (e.g. "TLS .pem-only behavior"). - **Docs PR tracking list gaps:** if any merged "Docs needed" or "Docs - changelog only" PR is absent from the **Docs Integration Tracking** checklist on the release docs PR, add it using the checklist format from the Assumptions section (unticked `[ ]`, correct section, author handle). - **Spelling/grammar fixes:** list each fix with file name and a short before → after summary. diff --git a/skills/write-changelog-item/SKILL.md b/skills/write-changelog-item/SKILL.md index 2b14e03f1..97ccf7d98 100644 --- a/skills/write-changelog-item/SKILL.md +++ b/skills/write-changelog-item/SKILL.md @@ -47,6 +47,14 @@ The changelog item should be benefit focused (highlight the why). The changelog item should be in the markdown format, don't remove ticks and markdown links, don't use bold and italic, use - at the beginning of the item. +Link the docs page for the change in the item whenever there is one: the page +from the docs PR for a **Docs needed** PR, or the existing page that covers the +changed flag, command or behavior. Link the section when there is one, with a +root-relative link: `[text search](/querying/text-search#create-text-index)`. +Readers and agents look at the release notes first to learn what changed; the +link takes them to how it works now. A bug fix with no page to point to needs +no link. + Usually the PR has the item written in one of the comments under the PR. Try to extract that first and improve according to the above description. From 4dfdaf722b25bd22028b4b1de38da5fdff7e8607 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:11:22 +0200 Subject: [PATCH 04/18] Create the docs milestone and handle patch releases in new-release-branch The skill now reads the version from the Memgraph milestone, creates the docs milestone that write-docs-page targets, puts the release PR in it, and appends the DOCS link to the Memgraph milestone description instead of replacing it. --- skills/new-release-branch/SKILL.md | 156 +++++++++++++++++++++-------- 1 file changed, 112 insertions(+), 44 deletions(-) diff --git a/skills/new-release-branch/SKILL.md b/skills/new-release-branch/SKILL.md index 10acfeac1..5dd032ec7 100644 --- a/skills/new-release-branch/SKILL.md +++ b/skills/new-release-branch/SKILL.md @@ -1,35 +1,80 @@ --- name: new-release-branch description: >- - Create a new release branch for Memgraph documentation with the initial - release-notes scaffold commit and PR. Use when the user wants to start a new - release, create a release branch, or prepare release notes for a new version. + Start a Memgraph documentation release: create the release branch and the + docs milestone, scaffold the release-notes titles, open the release PR and + link it from the Memgraph milestone. Works for minor (3.15) and patch + (3.13.2) releases. Use when the user wants to start a new release, create a + release branch or milestone, or prepare release notes for a new version. --- # New Release Branch -Automates the first commit of a new Memgraph documentation release branch: -creates the branch, scaffolds the release-notes titles, and opens a PR. +Sets up everything a release needs in the documentation repo, so that docs +PRs for the release have a branch and a milestone to target: + +- the release branch `release/` +- the docs milestone `` +- the release-notes titles on that branch +- the release PR, in the docs milestone, with the Docs Integration Tracking + checklist +- a `DOCS ->` link from the Memgraph milestone to the release PR + +The `write-docs-page` skill opens docs PRs on this branch and milestone and +never creates them itself, so create both as soon as the Memgraph milestone +exists. ## Step 1 — Gather information -Ask the user (use `AskQuestion` if available, otherwise ask conversationally): +Ask the user for: + +1. **Memgraph milestone** — URL or title, e.g. + `https://github.com/memgraph/memgraph/milestone/58` or `mg-v3.15.0`. +2. **Lab release** — whether Lab ships with this release and, if so, its + version. Minor releases usually have one; patch releases usually don't + (Lab patches get their own PR to `main`). + +Read the rest from the milestone: + +```bash +gh api repos/memgraph/memgraph/milestones/ \ + --jq '{title, due_on, description}' +``` -1. **Branch name** — exact name, e.g. `release/3.9`. -2. **Memgraph version + date** — e.g. `v3.9.0 - March 25th, 2026`. -3. **Lab version + date** — e.g. `v3.9.0 - March 25th, 2026`. -4. **GitHub milestone URL** — for the PR description, e.g. - `https://github.com/memgraph/memgraph/milestone/44`. +- **Version:** drop `mg-v` and a trailing `.0` from the title, the same rule + `write-docs-page` uses (`mg-v3.15.0` → `3.15`; a patch keeps its last + number, `mg-v3.13.2` → `3.13.2`). The version names the branch + (`release/3.15`) and the docs milestone (`3.15`). +- **Release notes version:** the full version from the title (`v3.15.0`, + `v3.13.2`). +- **Date:** the milestone's `due_on`, written like `December 2nd, 2026`. The + `pre-release` skill sets the real date on release day. + +If the branch already exists (`git ls-remote --heads origin release/`), +stop and tell the user: the release has already been started. + +## Step 2 — Create the docs milestone + +Check whether the docs milestone exists, and create it if it doesn't, with +the Memgraph milestone's due date: + +```bash +gh api "repos/memgraph/documentation/milestones?state=all&per_page=100" \ + --jq '.[] | select(.title == "") | .number' + +gh api repos/memgraph/documentation/milestones --method POST \ + -f title='' -f due_on='' +``` -## Step 2 — Create the branch +## Step 3 — Create the branch ```bash cd git checkout main && git pull -git checkout -b +git checkout -b release/ ``` -## Step 3 — Edit `pages/release-notes.mdx` +## Step 4 — Edit `pages/release-notes.mdx` The file has this high-level structure: @@ -48,9 +93,23 @@ The file has this high-level structure: ### Memgraph ... ``` -Make **two** changes (use `StrReplace` or equivalent): +### Patch release -### 3a — Add new empty titles above the current latest +Insert the new Memgraph title immediately after the line +`## 🚀 Latest release`, above the current entries, and move nothing: + +``` +### Memgraph - +``` + +The patch stays under "Latest release" with the minor release it patches. +Add a Lab title only if Lab ships with this patch. + +### Minor release + +Make **two** changes: + +#### 4a — Add new empty titles above the current latest Insert immediately after the line `## 🚀 Latest release`: @@ -62,7 +121,7 @@ Insert immediately after the line `## 🚀 Latest release`: ``` -### 3b — Move previous latest Memgraph + Lab into "Previous releases" +#### 4b — Move previous latest Memgraph + Lab into "Previous releases" Take the **entire previous latest block** — from the old `### Memgraph ` heading through the old @@ -96,35 +155,42 @@ The result should look like: **Important:** If there are multiple Memgraph patch releases under Latest (e.g. v3.8.1 and v3.8.0), move *all* of them together with the Lab entry. -**Implementation tip:** Do both changes in one `StrReplace` call by matching -from `## 🚀 Latest release` through `## Previous releases` and rewriting the +**Implementation tip:** Make both changes in one edit by matching from +`## 🚀 Latest release` through `## Previous releases` and rewriting the entire block at once. This avoids error-prone multi-step edits where `## Previous releases` can end up in the wrong place. -## Step 4 — Commit and push +Run `pnpm check` before committing; it checks that each `LabReleasesClient` +version matches its heading. + +## Step 5 — Commit and push ```bash git add pages/release-notes.mdx -git commit -m "Add Memgraph and Lab release note titles" -git push -u origin +git commit -m "Add Memgraph release note titles" +git push -u origin release/ ``` -## Step 5 — Create the PR +Name the Lab version in the commit message too when there is one. -Use `gh pr create`. The title should be: +## Step 6 — Create the PR -``` -Memgraph +Open a draft PR from `release/` into `main`, in the docs milestone: + +```bash +gh pr create --draft --base main --head release/ \ + --title "Memgraph " --milestone "" --body-file ``` Use this exact body template (fill in the placeholders): ~~~ Make sure to do: -* [ ] update direct download links +* [ ] run the `pre-release` skill (release dates, direct download links) Milestones -* Memgraph -> +* Memgraph -> +* Docs -> ### Docs Integration Tracking @@ -142,10 +208,10 @@ Milestones - [ ] https://github.com/memgraph/memgraph/pull/NNNN @author ~~~ -Replace `` with the actual URL provided by the user. -The `NNNN` / `MMMM` / `@author` / `short title` placeholders are filled in manually -as PRs are merged — remove the example lines and replace them with real entries. -Rules for each section: +The `NNNN` / `MMMM` / `@author` / `short title` placeholders are filled in +as PRs are merged — remove the example lines and replace them with real +entries (the `check-release-milestone` skill does this). Rules for each +section: - **Breaking changes PRs** — one line per merged PR carrying the `breaking` label. - **Docs needed** — one line per merged PR labeled `Docs needed`; end with the doc PR link (or `no doc PR yet`) and the code PR author's `@handle`. Tick `[x]` once the doc PR is merged. @@ -154,21 +220,23 @@ Rules for each section: it tracks the changelog entry independently of the doc page. Tick `[x]` once the entry lands in `release-notes.mdx`. -## Step 6 — Update the milestone description +Keep every list in ascending PR number order. + +## Step 7 — Link the release PR from the Memgraph milestone -Add a `DOCS ->` link back to the documentation PR in the GitHub milestone -description. Extract the milestone number from the milestone URL -(e.g. `49` from `https://github.com/memgraph/memgraph/milestone/49`) and the -PR number from the PR URL created in Step 5. +Add a `DOCS ->` line to the Memgraph milestone description. Keep what is +already there: read the description first and append the line. ```bash -gh api repos/memgraph/memgraph/milestones/ \ - --method PATCH \ - -f description='DOCS -> https://github.com/memgraph/documentation/pull/' +desc=$(gh api repos/memgraph/memgraph/milestones/ --jq '.description // ""') +gh api repos/memgraph/memgraph/milestones/ --method PATCH \ + -f description="${desc:+$desc +}DOCS -> https://github.com/memgraph/documentation/pull/" ``` -## Step 7 — Report back +## Step 8 — Report back -Print the PR URL and remind the user to: -- Fill in the PR/author placeholders in the PR description. -- Update the direct download links before merging. +Print the PR URL and the docs milestone URL, and remind the user to: +- Point docs PRs for the release at `release/` and the `` + milestone (`write-docs-page` does this on its own). +- Run `check-release-milestone` as PRs merge, and `pre-release` before merging. From b9f2bb0c13f32ea62489a6151e4b933417f25bcf Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:12:06 +0200 Subject: [PATCH 05/18] Check the docs milestone and run pnpm check in check-release-milestone Drop the grammar and cross-link steps: write-docs-page and CI cover them per PR. Report in chat instead of a Cursor canvas, drop the local tracking file, and name the skill after its folder. --- skills/check-release-milestone/SKILL.md | 84 +++++++++++-------------- 1 file changed, 38 insertions(+), 46 deletions(-) diff --git a/skills/check-release-milestone/SKILL.md b/skills/check-release-milestone/SKILL.md index b97393407..4021a67fd 100644 --- a/skills/check-release-milestone/SKILL.md +++ b/skills/check-release-milestone/SKILL.md @@ -1,11 +1,13 @@ --- -name: check_before_release -description: Run before every release to ensure all merged memgraph PRs have a docs label assigned, have changelog entries, have docs pages where required, that all changed text is free of spelling and grammar issues, and that existing documentation cross-links the new content. Use when preparing a release branch, before merging into the main branch, or when asked to "check before release". Also use standalone when asked to audit docs labels on a milestone. +name: check-release-milestone +description: Run during and before every release to ensure all merged memgraph PRs have a docs label assigned, have changelog entries and have docs pages where required, that the release PR's tracking checklist and the docs milestone match the Memgraph milestone, and that the release branch passes `pnpm check`. Use when preparing a release branch, before merging into the main branch, or when asked to "check before release". Also use standalone when asked to audit docs labels on a milestone. --- -# Check before release +# Check release milestone -Run this check before every release to audit docs labels on every merged PR, find PRs that are missing from the changelog or that have no documentation page despite being labeled "Docs needed", and to catch spelling/grammar issues in changed documentation. +Run this check as PRs merge and before every release to audit docs labels on every merged PR, find PRs that are missing from the changelog or that have no documentation page despite being labeled "Docs needed", and keep the release PR and the docs milestone in step with the Memgraph milestone. + +Writing quality is not checked here: docs PRs follow the `write-docs-page` skill (`memgraph/infra`, `agents/docs/skills/write-docs-page`), which covers names, terms and links to new pages, and CI checks links, anchors, names and Cypher examples. ## When to use @@ -16,7 +18,7 @@ Run this check before every release to audit docs labels on every merged PR, fin ## Assumptions - **PR list order:** Whenever you present a list of PRs to the user (gaps, backlog, - docs tracking, changelog queue, audit findings, canvas tables, etc.), sort by PR + docs tracking, changelog queue, audit findings, report tables, etc.), sort by PR number **ascending** (smallest → largest). Apply the same order when listing documentation PRs linked to memgraph PRs, unless the user asks for a different sort. - Memgraph PRs that need docs are labeled **"Docs needed"** or **"Docs - changelog only"**. @@ -66,16 +68,17 @@ Rules for this format: ``` gh pr view --repo memgraph/memgraph --json title,body,labels,author ``` - - Produce a **canvas** (read and follow `~/.cursor/skills-cursor/canvas/SKILL.md`) showing: + - Report in chat: - Summary stats: total merged, count per label, count needing attention. - - An "Issues requiring action" section listing PRs with missing or questionable labels, with a recommended label and a one-line reason (**sorted by PR # ascending**). - - A filterable table of all merged PRs with their current docs label highlighted (**default sort: PR # ascending**). + - An "Issues requiring action" table listing PRs with missing or questionable labels, with a recommended label and a one-line reason (**sorted by PR # ascending**). - **Fix or flag:** For PRs missing a label, recommend the correct one. For questionable ones, surface them to the reviewer — do not change the label unilaterally unless it is obviously wrong (e.g. no docs label at all on a pure test PR). 2. **Identify versions** - Current release (e.g. `3.9`) and previous one (e.g. `3.8.0`). - Memgraph milestone for the release (e.g. `mg-v3.9.0`, milestone 43). - - The open documentation release PR (e.g. `memgraph/documentation#1530`). + - The docs version, release branch and docs milestone: drop `mg-v` and a trailing `.0` from the Memgraph milestone title (`mg-v3.9.0` → `3.9`, `release/3.9`, docs milestone `3.9`; a patch keeps its last number, `mg-v3.13.2` → `3.13.2`). + - The open documentation release PR: linked as `DOCS ->` in the Memgraph milestone description (e.g. `memgraph/documentation#1530`). + - If the branch, the docs milestone or the release PR is missing, the release hasn't been started: run the `new-release-branch` skill first. 3. **Get the authoritative lists from the docs PR** - Fetch the PR body via `gh api repos/memgraph/documentation/pulls/ --jq .body`. @@ -98,62 +101,51 @@ Rules for this format: 5. **Docs page check** - For each memgraph PR in the **Docs needed** section, confirm the line links to a documentation PR (not `no doc PR yet`). - - Fetch the documentation milestone (e.g. `memgraph/documentation/milestone/`) and cross-reference: any doc PR in the milestone that maps to a memgraph "Docs needed" PR should be reflected on the docs PR's tracking list. - List any **docs page missing**: merged memgraph PRs labeled "Docs needed" with no corresponding doc PR on the tracking list. -6. **Grammar and spelling check** - - Run `git diff main...HEAD -- '*.mdx' '*.md'` (or the appropriate base branch) to get all text changes on the release branch. - - Review every added or modified line for: - - **Spelling mistakes** (typos, wrong words). - - **Broken sentence structure** (e.g. "Fixed X causes Y" instead of "Fixed a bug where X caused Y"). - - **Missing articles** ("creation of init container" → "creation of **an** init container"). - - **Wrong word forms** ("set-up" used as a verb → "set up"; "additionally to" → "in addition to"). - - **Stray punctuation** (accidental periods, double spaces in non-trailing positions). - - **Names and terms** that don't follow the writing rules engineers use, in the `write-docs-page` skill's `references/tone.md` (`memgraph/infra`, `agents/docs/skills/write-docs-page`): product names, MAIN and REPLICA in capitals (MAINs and REPLICAs in the plural), American English. Add a new naming rule there, not here, so docs written with the skill follow it too. - - - Do **not** rewrite for style or restructure paragraphs. Only fix clear errors: misspellings, missing/wrong articles, broken grammar, and wrong word forms. - - Apply fixes directly, then list what was changed in the report. - -7. **Cross-linking integration check** - - Run `git diff main...HEAD --name-only -- '*.mdx' '*.md'` to get every file changed on the release branch. - - For each changed file, identify the **key new concepts** it introduces (new pages, new sections, new Cypher commands, new configuration, renamed behavior). These are the integration targets. - - Scan the existing documentation on `main` for pages that discuss the same topic area but do **not** yet link to the new content. Efficient approach: - - Grep for related keywords (e.g. feature name, command name, config flag) across `pages/`. - - Check hub/landing pages (`_meta.ts` siblings, parent `.mdx` files) that list sub-pages — a new page may be missing from the hub. - - Check pages that mention the old behavior or a related workflow. - - Propose **up to 5** high-leverage, minimal edits. Prioritize: - 1. Hub/landing pages missing a link to a new sub-page or section. - 2. Pages that describe a related concept without linking to the new dedicated page (e.g. client-side parameters page not mentioning server-side parameters). - 3. Pages that reference a command or workflow whose behavior changed, where a one-line note + link avoids reader surprise. - - For each proposal, state: **file**, **location** (section or line range), **what to add** (sentence or callout), and **why** (what reader journey it fixes). - - After user approval, apply the edits directly. +6. **Docs milestone check** + - Fetch every PR in the docs milestone and every open or merged PR into the release branch: + ``` + gh pr list --repo memgraph/documentation --state all --search "milestone:" \ + --json number,title,state,baseRefName + gh pr list --repo memgraph/documentation --state all --base release/ \ + --json number,title,state,milestone + ``` + - Cross-reference: + - Every docs PR into `release/` (except closed-without-merge) is in the docs milestone. Add the missing ones to it. + - Every PR in the docs milestone targets `release/`. Flag the others. + - Every docs PR in the milestone that maps to a memgraph "Docs needed" PR is on the release PR's tracking list. + - The release PR itself is in the docs milestone. + - List open docs PRs in the milestone: they block the release. + +7. **Site checks** + - On the release branch, run `pnpm check` (links, section links, redirects, sidebar, release-note versions) and fix what it reports in the release notes. Report problems in other pages to the docs PR that introduced them. 8. **Report** - Sort every PR list in the report by PR number ascending (smallest → largest). - - **Docs label issues:** list every merged PR with a missing or questionable label, the recommended label, and a one-line reason. The canvas from step 1 serves as the primary deliverable for this section. - - **Not in changelog:** summarize all gaps (PR numbers and titles). When remediating, apply the **one item at a time** rule from step 4. For each gap, state that remediation follows **`write_changelog_item`** per `skills/write-changelog-item/SKILL.md` (unless the user asked for report-only). Include PRs found only via milestone cross-check. + - **Docs label issues:** list every merged PR with a missing or questionable label, the recommended label, and a one-line reason. + - **Not in changelog:** summarize all gaps (PR numbers and titles). When remediating, apply the **one item at a time** rule from step 4. For each gap, state that remediation follows **`write-changelog-item`** per `skills/write-changelog-item/SKILL.md` (unless the user asked for report-only). Include PRs found only via milestone cross-check. - **Missing docs links:** entries for **Docs needed** PRs that did not link their docs page, with the link added. - **Docs page missing:** list merged memgraph PRs labeled "Docs needed" with no doc PR on the tracking list; briefly note what's missing (e.g. "TLS .pem-only behavior"). - **Docs PR tracking list gaps:** if any merged "Docs needed" or "Docs - changelog only" PR is absent from the **Docs Integration Tracking** checklist on the release docs PR, add it using the checklist format from the Assumptions section (unticked `[ ]`, correct section, author handle). - - **Spelling/grammar fixes:** list each fix with file name and a short before → after summary. - - **Cross-link improvements:** list each proposed (or applied) edit with file, location, what was added, and why. - - If all lists are empty, state that the release is clear for label audit, changelog, docs, grammar, and cross-links. + - **Docs milestone gaps:** docs PRs added to the milestone, PRs in it with the wrong base, and open docs PRs that still block the release. + - **Site checks:** what `pnpm check` reported and what was fixed. + - If all lists are empty, state that the release is clear for label audit, changelog, docs pages, docs milestone and site checks. ## References -- **Canvas skill:** `~/.cursor/skills-cursor/canvas/SKILL.md` — required for producing the label audit canvas in step 1. +- **Starting a release:** `skills/new-release-branch/SKILL.md` — creates the release branch, docs milestone and release PR. - **Missing changelog items:** `skills/write-changelog-item/SKILL.md` — authoritative procedure to add entries and sync the docs release PR. - Memgraph commits (since last release): `https://github.com/memgraph/memgraph/commits/master/` - Memgraph milestone (e.g. 3.9): `https://github.com/memgraph/memgraph/milestone/43?closed=1` +- Docs milestones: `https://github.com/memgraph/documentation/milestones` - Release notes file: `pages/release-notes.mdx` - Documentation release PR: linked from the milestone or repo (e.g. `memgraph/documentation` open PR for the release). ## Notes -- **Label audit scope:** Step 1 can be run standalone (without the full release check) when asked to "audit docs labels" or "check labels on milestone". When run standalone, produce only the canvas and a brief chat summary — skip steps 2–8. +- **Label audit scope:** Step 1 can be run standalone (without the full release check) when asked to "audit docs labels" or "check labels on milestone". When run standalone, produce only the step 1 report — skip steps 2–8. - **Changelog workflow:** Multiple missing entries are common; never merge several proposed bullets into one reviewer-facing message. One PR → one proposed changelog item → pause for review → next PR. - **Merged PRs only:** always filter the milestone by `merged_at != null` (use `gh api "repos/memgraph/memgraph/issues?milestone=&state=closed" --jq '[.[] | select(.pull_request != null and .pull_request.merged_at != null)]'`). Closed-without-merge PRs must be ignored entirely. - PRs labeled **"Docs unnecessary"** (e.g. CI, tests, internal tooling) are excluded; no changelog or docs page required. -- If work landed in a different PR than originally planned, the changelog should reference the **merged** PR that shipped the behavior; if user-visible behavior still has no line in `release-notes.mdx`, treat it as a gap and use **write_changelog_item**. -- The grammar check scope is the diff against `main` (or the base branch). Existing text that was not touched in this release is out of scope. -- When writing the local tracking file (`.release-tracking/vX.Y.Z.md`), keep it in sync with the docs PR body — both should reflect the same checklist state. +- If work landed in a different PR than originally planned, the changelog should reference the **merged** PR that shipped the behavior; if user-visible behavior still has no line in `release-notes.mdx`, treat it as a gap and use **write-changelog-item**. From cd9c360787de673f3b7067473ba93e927a021b1c Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:12:19 +0200 Subject: [PATCH 06/18] Fold the bug-fix wording rule into write-changelog-item Lead a bug-fix entry with what works now, not how it used to fail. Also name the skill after its folder. --- skills/write-changelog-item/SKILL.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/skills/write-changelog-item/SKILL.md b/skills/write-changelog-item/SKILL.md index 97ccf7d98..954cbeeb2 100644 --- a/skills/write-changelog-item/SKILL.md +++ b/skills/write-changelog-item/SKILL.md @@ -1,5 +1,5 @@ --- -name: write_changelog_item +name: write-changelog-item description: Create/write the changelog item / release note for a given Github PR and update the docs release PR description. --- @@ -23,6 +23,9 @@ Write for someone who runs Memgraph, writes Cypher, operates a cluster, or authors modules — not for someone reading the PR diff. Prefer: - What changed for the user (faster connect, no crash, new query, new flag). +- For a bug fix, what works now: "Edge vector indexes recover correctly after + a crash or snapshot load." Add the trigger only when it helps an operator + recognize the situation ("while a new MAIN's first commit arrives"). - Symptoms and outcomes over internals (cache key, planner rewrite, cursor). - Plain language; spell out jargon unless it is a product term the user already knows (`EXISTS`, `SHOW INSTANCES`, config flag names). @@ -33,7 +36,8 @@ authors modules — not for someone reading the PR diff. Prefer: Avoid: - Describing the implementation ("rewrote X as Y", "removed the Limit - operator the branch never needed"). + operator the branch never needed"), including how a bug used to fail: the + crash path, the race, the dangling pointer or the missing lock. - Wording that sounds like a recommendation not to use a feature (e.g. "faster when permissions are not used") when the point is that unnecessary work was removed. From d9c295f8246a16b6833f5eba5f2fec0083e81605 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:12:19 +0200 Subject: [PATCH 07/18] Check the release PR and close the docs milestone in pre-release --- skills/pre-release/SKILL.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/skills/pre-release/SKILL.md b/skills/pre-release/SKILL.md index d86ac6c9e..f0983e295 100644 --- a/skills/pre-release/SKILL.md +++ b/skills/pre-release/SKILL.md @@ -1,6 +1,6 @@ --- name: pre-release -description: Run final pre-release tasks for the documentation site. Updates release note dates and direct download links to the new Memgraph version. Use when preparing a documentation release, before publishing, or when asked to run "pre-release" steps. +description: Run final pre-release tasks for the documentation site. Updates release note dates and direct download links to the new Memgraph version, checks the release PR is ready, and closes the docs milestone after the merge. Use when preparing a documentation release, before publishing, or when asked to run "pre-release" steps. --- # Pre-release @@ -42,3 +42,21 @@ replace **every** occurrence of the previous version with the new one. `3.9.0`) — this covers both patterns in a single pass. - Verify the result: every URL in the file should reference only the new version. + +### 3. Check the release PR is ready + +- Run `pnpm check` on the release branch; it checks links, redirects, the + sidebar and that each release-note heading loads the matching version. +- Every item on the release PR's Docs Integration Tracking checklist is + ticked, and the docs milestone has no open PRs other than the release PR. + If anything is left, run the `check-release-milestone` skill. + +### 4. After the release PR is merged + +Close the docs milestone. If PRs are still open in it, ask the user whether +to move them to the next release's milestone first. + +```bash +gh api repos/memgraph/documentation/milestones/ \ + --method PATCH -f state=closed +``` From b1c3f6d466a8861da7cf268a46f92f13d5596ac3 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:12:29 +0200 Subject: [PATCH 08/18] List the release skills in AGENTS.md --- AGENTS.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7d7b46660..03ade2330 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,12 @@ The short version, for everyone: ## Branches and PRs - Docs for a product change go to the docs release branch for that release - (`release/`); other changes go to `main`. + (`release/`, in the docs milestone ``); other changes go + to `main`. +- Releases follow the skills in `skills/`: `new-release-branch` creates the + release branch, docs milestone and release PR; `check-release-milestone` + keeps them in step with the Memgraph milestone; `write-changelog-item` + writes each release note; `pre-release` runs on release day. - Use `.github/pull_request_template.md` and name the product PR as `memgraph/memgraph#NNNN`. From a4ea399dec5551bf75fc80b9f2d4113065d65548 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:17:37 +0200 Subject: [PATCH 09/18] Stop updating the release PR description from write-changelog-item check-release now works out what is missing from the milestones and labels, so the release PR no longer keeps a tracking checklist. --- skills/write-changelog-item/SKILL.md | 36 +++++----------------------- 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/skills/write-changelog-item/SKILL.md b/skills/write-changelog-item/SKILL.md index 954cbeeb2..11b1a4c40 100644 --- a/skills/write-changelog-item/SKILL.md +++ b/skills/write-changelog-item/SKILL.md @@ -1,6 +1,6 @@ --- name: write-changelog-item -description: Create/write the changelog item / release note for a given Github PR and update the docs release PR description. +description: Create/write the changelog item / release note for a given Github PR in `pages/release-notes.mdx` on the release branch. Use when asked to write a release note or changelog entry, or when `check-release` finds a PR missing from the release notes. --- For a given Github PR write a changelog item. @@ -78,9 +78,8 @@ that should be **only in the release notes**, or whether it needs to be Apply this check primarily when the memgraph PR is labeled **`Docs - changelog only`**. If it is labeled **`Docs needed`**, a docs page -(or docs PR) is expected as part of the normal docs workflow — track it on the -release docs PR, but do not treat "should this go into the docs?" as an open -question for that label. +(or docs PR) is expected as part of the normal docs workflow, so do not treat +"should this go into the docs?" as an open question for that label. For **`Docs - changelog only`**, before proposing or applying a changelog bullet, ask: @@ -105,9 +104,9 @@ Then decide and **surface the decision to the reviewer** with the draft: Grep the repo for the new flag, command, or concept name before claiming it is undocumented. -For **`Docs needed`**, point at the linked docs PR (or `no doc PR yet` on the -tracking list). Keep the release-note bullet aligned with that docs wording -where useful. +For **`Docs needed`**, find the docs PR (its body names the product PR as +`memgraph/memgraph#NNNN`) and keep the release-note bullet aligned with its +wording where useful. If there is none yet, say so. Any docs text you write for propagation must follow the same user-friendly, user-centric rules as the release note. @@ -121,26 +120,3 @@ user-centric rules as the release note. end unless this PR is the highest number already in that section. 3. Do not re-sort an in-progress release to fix historical ordering unless the user explicitly asks. - -## Updating the docs release PR description - -After writing the changelog item in `pages/release-notes.mdx`, also update the -description of the open documentation release PR (e.g. -`memgraph/documentation#1530` for 3.9) so the PR keeps a complete overview of -everything integrated in the release. - -1. Fetch the current PR body via `gh api`. -2. In the **Docs Integration Tracking** section, add the memgraph PR to - **Changelog (all PRs requiring a changelog entry)** if it is not already - listed, or tick its line. Use the format the section already uses: - `- [x] https://github.com/memgraph/memgraph/pull/XXXX @author` - Keep the list in ascending PR number order. -3. If the memgraph PR has the **"Docs needed"** label, also make sure it is - listed under **Docs needed (Memgraph PR → Docs PR)**: - `- [x] https://github.com/memgraph/memgraph/pull/XXXX → https://github.com/memgraph/documentation/pull/YYYY @author` - Tick it only when the docs PR exists; otherwise leave it unticked with - `→ no doc PR yet`. -4. If the memgraph PR has the `breaking` label, make sure it is listed under - **Breaking changes PRs**: - `- [x] https://github.com/memgraph/memgraph/pull/XXXX — short title @author` -5. Push the updated body back via `gh api ... -X PATCH -F "body=@file"`. From b2052e1daca4f54e276976643704576672238f96 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:17:51 +0200 Subject: [PATCH 10/18] Drop the tracking checklist from the release PR in new-release-branch --- skills/new-release-branch/SKILL.md | 43 ++++++------------------------ 1 file changed, 8 insertions(+), 35 deletions(-) diff --git a/skills/new-release-branch/SKILL.md b/skills/new-release-branch/SKILL.md index 5dd032ec7..45e9ef4af 100644 --- a/skills/new-release-branch/SKILL.md +++ b/skills/new-release-branch/SKILL.md @@ -16,8 +16,7 @@ PRs for the release have a branch and a milestone to target: - the release branch `release/` - the docs milestone `` - the release-notes titles on that branch -- the release PR, in the docs milestone, with the Docs Integration Tracking - checklist +- the release PR, in the docs milestone - a `DOCS ->` link from the Memgraph milestone to the release PR The `write-docs-page` skill opens docs PRs on this branch and milestone and @@ -48,7 +47,7 @@ gh api repos/memgraph/memgraph/milestones/ \ - **Release notes version:** the full version from the title (`v3.15.0`, `v3.13.2`). - **Date:** the milestone's `due_on`, written like `December 2nd, 2026`. The - `pre-release` skill sets the real date on release day. + `check-release` skill sets the real date on release day. If the branch already exists (`git ls-remote --heads origin release/`), stop and tell the user: the release has already been started. @@ -182,45 +181,19 @@ gh pr create --draft --base main --head release/ \ --title "Memgraph " --milestone "" --body-file ``` -Use this exact body template (fill in the placeholders): +Use this body (fill in the placeholders): ~~~ -Make sure to do: -* [ ] run the `pre-release` skill (release dates, direct download links) - Milestones * Memgraph -> * Docs -> -### Docs Integration Tracking - -#### Breaking changes PRs - -- [ ] https://github.com/memgraph/memgraph/pull/NNNN — short title @author - -#### Docs needed (Memgraph PR → Docs PR) - -- [ ] https://github.com/memgraph/memgraph/pull/NNNN → https://github.com/memgraph/documentation/pull/MMMM @author -- [ ] https://github.com/memgraph/memgraph/pull/NNNN → no doc PR yet @author - -#### Changelog (all PRs requiring a changelog entry) - -- [ ] https://github.com/memgraph/memgraph/pull/NNNN @author +Run the `check-release` skill to see what the release still needs; run it +with "release day" before merging. ~~~ -The `NNNN` / `MMMM` / `@author` / `short title` placeholders are filled in -as PRs are merged — remove the example lines and replace them with real -entries (the `check-release-milestone` skill does this). Rules for each -section: -- **Breaking changes PRs** — one line per merged PR carrying the `breaking` label. -- **Docs needed** — one line per merged PR labeled `Docs needed`; end with the doc PR link - (or `no doc PR yet`) and the code PR author's `@handle`. Tick `[x]` once the doc PR is merged. -- **Changelog** — one line per merged PR labeled `Docs needed` **or** `Docs - changelog only`; - end with the author's `@handle`. This section deliberately duplicates `Docs needed` entries — - it tracks the changelog entry independently of the doc page. Tick `[x]` once the entry lands - in `release-notes.mdx`. - -Keep every list in ascending PR number order. +The PR keeps no checklist of product PRs: `check-release` works out what is +missing from the Memgraph milestone, its docs labels and the docs milestone. ## Step 7 — Link the release PR from the Memgraph milestone @@ -239,4 +212,4 @@ gh api repos/memgraph/memgraph/milestones/ --method PATCH \ Print the PR URL and the docs milestone URL, and remind the user to: - Point docs PRs for the release at `release/` and the `` milestone (`write-docs-page` does this on its own). -- Run `check-release-milestone` as PRs merge, and `pre-release` before merging. +- Run `check-release` as PRs merge, and on release day before merging. From aad55a35fdc2c699f1890d2789d6c28cb6329fe8 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 11:19:09 +0200 Subject: [PATCH 11/18] Merge check-release-milestone and pre-release into check-release check-release works out what is missing from the Memgraph milestone, the docs labels and the docs milestone instead of a checklist in the release PR, and on release day sets the dates, updates the download links and closes the docs milestone. --- AGENTS.md | 6 +- skills/check-release-milestone/SKILL.md | 151 ------------------- skills/check-release/SKILL.md | 184 ++++++++++++++++++++++++ skills/pre-release/SKILL.md | 62 -------- 4 files changed, 187 insertions(+), 216 deletions(-) delete mode 100644 skills/check-release-milestone/SKILL.md create mode 100644 skills/check-release/SKILL.md delete mode 100644 skills/pre-release/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index 03ade2330..f79902163 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,9 +38,9 @@ The short version, for everyone: (`release/`, in the docs milestone ``); other changes go to `main`. - Releases follow the skills in `skills/`: `new-release-branch` creates the - release branch, docs milestone and release PR; `check-release-milestone` - keeps them in step with the Memgraph milestone; `write-changelog-item` - writes each release note; `pre-release` runs on release day. + release branch, docs milestone and release PR; `write-changelog-item` + writes each release note; `check-release` finds what the release still + needs and, on release day, finishes it. - Use `.github/pull_request_template.md` and name the product PR as `memgraph/memgraph#NNNN`. diff --git a/skills/check-release-milestone/SKILL.md b/skills/check-release-milestone/SKILL.md deleted file mode 100644 index 4021a67fd..000000000 --- a/skills/check-release-milestone/SKILL.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -name: check-release-milestone -description: Run during and before every release to ensure all merged memgraph PRs have a docs label assigned, have changelog entries and have docs pages where required, that the release PR's tracking checklist and the docs milestone match the Memgraph milestone, and that the release branch passes `pnpm check`. Use when preparing a release branch, before merging into the main branch, or when asked to "check before release". Also use standalone when asked to audit docs labels on a milestone. ---- - -# Check release milestone - -Run this check as PRs merge and before every release to audit docs labels on every merged PR, find PRs that are missing from the changelog or that have no documentation page despite being labeled "Docs needed", and keep the release PR and the docs milestone in step with the Memgraph milestone. - -Writing quality is not checked here: docs PRs follow the `write-docs-page` skill (`memgraph/infra`, `agents/docs/skills/write-docs-page`), which covers names, terms and links to new pages, and CI checks links, anchors, names and Cypher examples. - -## When to use - -- Before merging the main release documentation PR (e.g. `memgraph/documentation#1530` for 3.9) -- When preparing or validating a release branch -- When asked to verify release readiness for docs/changelog - -## Assumptions - -- **PR list order:** Whenever you present a list of PRs to the user (gaps, backlog, - docs tracking, changelog queue, audit findings, report tables, etc.), sort by PR - number **ascending** (smallest → largest). Apply the same order when listing - documentation PRs linked to memgraph PRs, unless the user asks for a different sort. -- Memgraph PRs that need docs are labeled **"Docs needed"** or **"Docs - changelog only"**. -- Only consider **merged** PRs (i.e. `merged_at != null`). PRs that are closed without merging must be ignored entirely — no changelog entry, no doc page, not in the tracking list. -- The release documentation PR (in `memgraph/documentation`) uses the following **Docs Integration Tracking** format (three plain checklist sections — no tables): - -``` -#### Breaking changes PRs - -- [ ] https://github.com/memgraph/memgraph/pull/NNNN — short title @author - -#### Docs needed (Memgraph PR → Docs PR) - -- [ ] https://github.com/memgraph/memgraph/pull/NNNN → https://github.com/memgraph/documentation/pull/MMMM @author -- [ ] https://github.com/memgraph/memgraph/pull/NNNN → no doc PR yet @author - -#### Changelog (all PRs requiring a changelog entry) - -- [ ] https://github.com/memgraph/memgraph/pull/NNNN @author -``` - -Rules for this format: -- **Breaking changes PRs** — every merged PR with the `breaking` label (one line each). -- **Docs needed** — every merged PR labeled `Docs needed`. Each line ends with the doc PR link (or `no doc PR yet` if none exists) and the code PR author's GitHub handle. -- **Changelog** — every merged PR labeled `Docs needed` **or** `Docs - changelog only`. This section deliberately duplicates `Docs needed` PRs — it tracks the changelog entry independently of the doc page. Each line ends with the code PR author's handle. -- Tick `[x]` when the item is complete. GitHub renders `[ ]` as a clickable checkbox so reviewers can tick without editing markdown. - -## Steps - -1. **Docs label audit** - - Fetch every merged PR in the milestone: - ``` - gh api "repos/memgraph/memgraph/issues?milestone=&state=closed&per_page=100" \ - --jq '[.[] | select(.pull_request != null and .pull_request.merged_at != null)] | - map({number, title, author: .user.login, - docs_labels: [.labels[].name | select(startswith("Docs"))]})[]' - ``` - - For each merged PR classify its docs label state: - - **OK** — exactly one of: `Docs needed`, `Docs - changelog only`, `Docs unnecessary`. - - **Missing label** — no docs label at all. - - **Questionable** — the assigned label appears inconsistent with the PR content (e.g. a pure CI/test PR carrying `Docs needed`, or a user-facing feature carrying `Docs unnecessary`). - - Apply these heuristics to spot questionable labels: - - PRs whose title starts with `test:`, `testing:`, `tests:`, `ci:`, `infra:`, or `refactor:` and whose labels include only `infrastructure`, `tests`, `benchmarking`, or `Code improvements` almost always warrant `Docs unnecessary`. - - PRs labeled `feature` that carry `Docs unnecessary` should be scrutinised — only internal-only features (no new flags, commands, or user-visible behavior) are legitimately `Docs unnecessary`. - - Build-system / packaging PRs (Conan, CMake, Docker CI changes) are normally `Docs unnecessary` unless they change how end-users build or install Memgraph. - - For PRs where the label is missing or questionable, fetch the PR body for context: - ``` - gh pr view --repo memgraph/memgraph --json title,body,labels,author - ``` - - Report in chat: - - Summary stats: total merged, count per label, count needing attention. - - An "Issues requiring action" table listing PRs with missing or questionable labels, with a recommended label and a one-line reason (**sorted by PR # ascending**). - - **Fix or flag:** For PRs missing a label, recommend the correct one. For questionable ones, surface them to the reviewer — do not change the label unilaterally unless it is obviously wrong (e.g. no docs label at all on a pure test PR). - -2. **Identify versions** - - Current release (e.g. `3.9`) and previous one (e.g. `3.8.0`). - - Memgraph milestone for the release (e.g. `mg-v3.9.0`, milestone 43). - - The docs version, release branch and docs milestone: drop `mg-v` and a trailing `.0` from the Memgraph milestone title (`mg-v3.9.0` → `3.9`, `release/3.9`, docs milestone `3.9`; a patch keeps its last number, `mg-v3.13.2` → `3.13.2`). - - The open documentation release PR: linked as `DOCS ->` in the Memgraph milestone description (e.g. `memgraph/documentation#1530`). - - If the branch, the docs milestone or the release PR is missing, the release hasn't been started: run the `new-release-branch` skill first. - -3. **Get the authoritative lists from the docs PR** - - Fetch the PR body via `gh api repos/memgraph/documentation/pulls/ --jq .body`. - - From the **Docs Integration Tracking** section, extract: - - Every **Docs needed** line: memgraph PR # and linked doc PR # (or "no doc PR yet"). - - Every **Changelog** line: memgraph PR # (all PRs that need a changelog entry). - - Every **Breaking changes PRs** line: memgraph PR # marked as breaking. - - Cross-check against the memgraph milestone (closed + merged only) to catch any PRs the docs PR has not yet listed. - -4. **Changelog check** - - Open `pages/release-notes.mdx` and locate the section for the new release (e.g. `### Memgraph v3.9.0`). - - For each PR in **Changelog**, confirm it appears in that section (e.g. as `[#NNNN](https://github.com/memgraph/memgraph/pull/NNNN)` or equivalent). - - For each PR in **Docs needed**, confirm its entry links to the docs page for the change (a root-relative link such as `/querying/text-search#create-text-index`). The docs CI checks that the page and section exist; this step checks that the link is there. List entries without one as **missing docs link** and add the link. - - Optionally cross-check the memgraph milestone: merged PRs with user-visible work (e.g. **Docs needed**, **Docs - changelog only**) that are absent from that release section should also be treated as **missing from changelog**, even if they were never added to **Changelog** on the docs PR. - - List any **missing from changelog** with PR numbers (and titles if known). - - **If anything is missing from the changelog:** follow **`skills/write-changelog-item/SKILL.md`** end-to-end for each gap. That skill defines how to write the item (user-friendly / user-centric impact, not engineering work; markdown; PR link; breaking vs non-breaking; whether the change is release-notes-only or must also be propagated into the docs), where to place it in `pages/release-notes.mdx` (correct section, ascending PR # within the section), and requires updating `pages/release-notes.mdx` plus keeping the open documentation release PR description aligned. When updating the docs PR body, use the **Docs Integration Tracking** checklist format described in the Assumptions section — tick `[x]` on the relevant **Changelog** line and, if the PR is also "Docs needed", on the **Docs needed** line once a doc PR exists. Do not use a different format or skip the release PR body update. - - **One item at a time:** When proposing or drafting changelog text, handle **a single PR / single bullet** per turn. Give the full proposed entry (wording, PR link, breaking vs non-breaking if relevant) and any file or release-PR body edits that go with that one item, then **stop and wait for reviewer feedback** before moving to the next missing item. Do not batch multiple proposed changelog bullets or multiple PR remediations in one message — the reviewer must be able to approve, edit, or reject each entry on its own. - -5. **Docs page check** - - For each memgraph PR in the **Docs needed** section, confirm the line links to a documentation PR (not `no doc PR yet`). - - List any **docs page missing**: merged memgraph PRs labeled "Docs needed" with no corresponding doc PR on the tracking list. - -6. **Docs milestone check** - - Fetch every PR in the docs milestone and every open or merged PR into the release branch: - ``` - gh pr list --repo memgraph/documentation --state all --search "milestone:" \ - --json number,title,state,baseRefName - gh pr list --repo memgraph/documentation --state all --base release/ \ - --json number,title,state,milestone - ``` - - Cross-reference: - - Every docs PR into `release/` (except closed-without-merge) is in the docs milestone. Add the missing ones to it. - - Every PR in the docs milestone targets `release/`. Flag the others. - - Every docs PR in the milestone that maps to a memgraph "Docs needed" PR is on the release PR's tracking list. - - The release PR itself is in the docs milestone. - - List open docs PRs in the milestone: they block the release. - -7. **Site checks** - - On the release branch, run `pnpm check` (links, section links, redirects, sidebar, release-note versions) and fix what it reports in the release notes. Report problems in other pages to the docs PR that introduced them. - -8. **Report** - - Sort every PR list in the report by PR number ascending (smallest → largest). - - **Docs label issues:** list every merged PR with a missing or questionable label, the recommended label, and a one-line reason. - - **Not in changelog:** summarize all gaps (PR numbers and titles). When remediating, apply the **one item at a time** rule from step 4. For each gap, state that remediation follows **`write-changelog-item`** per `skills/write-changelog-item/SKILL.md` (unless the user asked for report-only). Include PRs found only via milestone cross-check. - - **Missing docs links:** entries for **Docs needed** PRs that did not link their docs page, with the link added. - - **Docs page missing:** list merged memgraph PRs labeled "Docs needed" with no doc PR on the tracking list; briefly note what's missing (e.g. "TLS .pem-only behavior"). - - **Docs PR tracking list gaps:** if any merged "Docs needed" or "Docs - changelog only" PR is absent from the **Docs Integration Tracking** checklist on the release docs PR, add it using the checklist format from the Assumptions section (unticked `[ ]`, correct section, author handle). - - **Docs milestone gaps:** docs PRs added to the milestone, PRs in it with the wrong base, and open docs PRs that still block the release. - - **Site checks:** what `pnpm check` reported and what was fixed. - - If all lists are empty, state that the release is clear for label audit, changelog, docs pages, docs milestone and site checks. - -## References - -- **Starting a release:** `skills/new-release-branch/SKILL.md` — creates the release branch, docs milestone and release PR. -- **Missing changelog items:** `skills/write-changelog-item/SKILL.md` — authoritative procedure to add entries and sync the docs release PR. -- Memgraph commits (since last release): `https://github.com/memgraph/memgraph/commits/master/` -- Memgraph milestone (e.g. 3.9): `https://github.com/memgraph/memgraph/milestone/43?closed=1` -- Docs milestones: `https://github.com/memgraph/documentation/milestones` -- Release notes file: `pages/release-notes.mdx` -- Documentation release PR: linked from the milestone or repo (e.g. `memgraph/documentation` open PR for the release). - -## Notes - -- **Label audit scope:** Step 1 can be run standalone (without the full release check) when asked to "audit docs labels" or "check labels on milestone". When run standalone, produce only the step 1 report — skip steps 2–8. -- **Changelog workflow:** Multiple missing entries are common; never merge several proposed bullets into one reviewer-facing message. One PR → one proposed changelog item → pause for review → next PR. -- **Merged PRs only:** always filter the milestone by `merged_at != null` (use `gh api "repos/memgraph/memgraph/issues?milestone=&state=closed" --jq '[.[] | select(.pull_request != null and .pull_request.merged_at != null)]'`). Closed-without-merge PRs must be ignored entirely. -- PRs labeled **"Docs unnecessary"** (e.g. CI, tests, internal tooling) are excluded; no changelog or docs page required. -- If work landed in a different PR than originally planned, the changelog should reference the **merged** PR that shipped the behavior; if user-visible behavior still has no line in `release-notes.mdx`, treat it as a gap and use **write-changelog-item**. diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md new file mode 100644 index 000000000..c848c26a8 --- /dev/null +++ b/skills/check-release/SKILL.md @@ -0,0 +1,184 @@ +--- +name: check-release +description: Find what a Memgraph documentation release still needs, and on release day finish it. Checks the docs labels on every merged PR in the Memgraph milestone, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. +--- + +# Check release + +Works out what a release still needs from GitHub itself — the Memgraph +milestone, the docs labels on its PRs, the docs milestone and the release +branch — so nothing has to be tracked by hand. Run it as often as needed +while the release is in progress. On release day, run it once more and +finish with the release-day steps. + +Writing quality is not checked here: docs PRs follow the `write-docs-page` +skill (`memgraph/infra`, `agents/docs/skills/write-docs-page`), which covers +names, terms and links to new pages, and CI checks links, anchors, names and +Cypher examples. + +## Rules + +- **Merged PRs only:** a Memgraph PR counts once `merged_at != null`. PRs + closed without merging are ignored entirely. +- **Docs labels:** every merged PR carries exactly one of `Docs needed`, + `Docs - changelog only` or `Docs unnecessary`. `Docs needed` means a docs + PR and a release note; `Docs - changelog only` means a release note; + `Docs unnecessary` means neither. +- **PR order:** sort every list of PRs by PR number ascending (smallest → + largest). +- **One release note at a time:** when a release note is missing, draft + **one** entry with `skills/write-changelog-item/SKILL.md`, then stop and + wait for the reviewer before the next one. Never batch several entries + into one message. + +## Steps + +### 1. Find the release + +From the version or Memgraph milestone the user gives (e.g. `mg-v3.15.0`): + +- **Version:** drop `mg-v` and a trailing `.0` from the milestone title + (`mg-v3.15.0` → `3.15`; a patch keeps its last number, `mg-v3.13.2` → + `3.13.2`). +- **Release branch** `release/`, **docs milestone** ``, and + the **release PR**, linked as `DOCS ->` in the Memgraph milestone + description. +- **Release notes section:** the `### Memgraph v` heading in + `pages/release-notes.mdx` on the release branch. + +If the branch, the docs milestone or the release PR is missing, the release +hasn't been started: run the `new-release-branch` skill first. + +Fetch every merged PR in the Memgraph milestone once and reuse it below: + +```bash +gh api --paginate "repos/memgraph/memgraph/issues?milestone=&state=closed&per_page=100" \ + --jq '.[] | select(.pull_request != null and .pull_request.merged_at != null) | + {number, title, author: .user.login, labels: [.labels[].name]}' +``` + +### 2. Docs labels + +Classify each merged PR: + +- **OK** — exactly one docs label. +- **Missing label** — no docs label. +- **Questionable** — the label looks inconsistent with the PR. Heuristics: + - PRs whose title starts with `test:`, `testing:`, `tests:`, `ci:`, + `infra:` or `refactor:` and whose labels include only `infrastructure`, + `tests`, `benchmarking` or `Code improvements` almost always warrant + `Docs unnecessary`. + - PRs labeled `feature` that carry `Docs unnecessary` should be + scrutinised — only internal-only features (no new flags, commands or + user-visible behavior) are legitimately `Docs unnecessary`. + - Build-system / packaging PRs (Conan, CMake, Docker CI changes) are + normally `Docs unnecessary` unless they change how end-users build or + install Memgraph. + +For missing or questionable labels, read the PR +(`gh pr view --repo memgraph/memgraph --json title,body,labels,author`) +and recommend a label with a one-line reason. Do not change a label yourself +unless it is obviously wrong (e.g. no docs label at all on a pure test PR). + +When asked only to "audit docs labels", stop after this step and report. + +### 3. Release notes + +In the release notes section on the release branch: + +- Every merged PR labeled `Docs needed` or `Docs - changelog only` has an + entry with its PR link (`[#NNNN](https://github.com/memgraph/memgraph/pull/NNNN)`). + If work landed in a different PR than planned, the entry references the + merged PR that shipped the behavior. +- Every PR labeled `breaking` is under the Breaking changes heading, and only + there. +- Every `Docs needed` entry links the docs page for the change (a + root-relative link such as `/querying/text-search#create-text-index`). CI + checks the page and section exist; this step checks the link is there. + +Fix each gap with `write-changelog-item`, one entry at a time. + +### 4. Docs PRs + +List the docs PRs for the release and the product PRs they name (a docs PR +names its product PR as `memgraph/memgraph#NNNN`): + +```bash +gh pr list --repo memgraph/documentation --state all --search "milestone:" \ + --json number,state,baseRefName,body \ + --jq '.[] | {number, state, base: .baseRefName, + product: [.body | scan("memgraph/memgraph(?:#|/pull/)([0-9]+)") | .[0]]}' +``` + +- Ignore docs PRs in state `CLOSED`: they were closed without merging. +- Every merged PR labeled `Docs needed` has a docs PR. If none names it, + check the product PR's "Documentation PR link" comment + (`gh api repos/memgraph/memgraph/issues//comments`) before calling it + missing. +- Open docs PRs still block the release. + +### 5. Docs milestone + +- Every docs PR into `release/` (except closed-without-merge) is in + the docs milestone; add the missing ones: + `gh pr list --repo memgraph/documentation --state all --base release/ --json number,state,milestone`. +- Every PR in the docs milestone targets `release/`; flag the others. +- The release PR is in the docs milestone. + +### 6. Site checks + +On the release branch, run `pnpm check` (links, section links, redirects, +sidebar, release-note versions). Fix what it reports in the release notes; +report problems in other pages to the docs PR that introduced them. + +### 7. Report + +Sort every PR list by PR number ascending, and skip sections with nothing to +report: + +- **Docs labels:** missing or questionable labels, the recommended label and + a one-line reason. +- **Release notes:** PRs with no entry, breaking changes outside the Breaking + section, `Docs needed` entries with no docs link. +- **Docs PRs:** `Docs needed` PRs with no docs PR (with the author's + `@handle`), and open docs PRs. +- **Docs milestone:** PRs added to it, PRs in it with the wrong base. +- **Site checks:** what `pnpm check` reported and what was fixed. + +If every section is empty, say the release is ready. + +## Release day + +Run these only when the user says it's release day, after steps 1–7 report +the release ready. + +### 8. Set the release dates + +In `pages/release-notes.mdx`, set the date on the release's +`### Memgraph v - ` heading (and its `### Lab v - +` heading, if Lab ships with it) to today, in the same format (e.g. +`May 6th, 2026` → `May 13th, 2026`). + +### 9. Update the direct download links + +In `pages/getting-started/install-memgraph/direct-download-links.mdx`, +replace **every** occurrence of the previous version with the new one. + +- The file has download URLs for Docker, CentOS, Debian, Fedora, Rocky, Red + Hat and Ubuntu packages, with the version both in path segments (`v3.8.1`) + and file names (`3.8.1`). +- A global find-and-replace of the bare old version string (e.g. `3.8.1` → + `3.9.0`) covers both patterns in one pass. +- Verify every URL in the file references only the new version. + +Run `pnpm check` again, then commit and push to the release branch. + +### 10. After the release PR is merged + +Close the docs milestone. If PRs are still open in it, ask the user whether +to move them to the next release's milestone first. + +```bash +gh api repos/memgraph/documentation/milestones/ \ + --method PATCH -f state=closed +``` diff --git a/skills/pre-release/SKILL.md b/skills/pre-release/SKILL.md deleted file mode 100644 index f0983e295..000000000 --- a/skills/pre-release/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: pre-release -description: Run final pre-release tasks for the documentation site. Updates release note dates and direct download links to the new Memgraph version, checks the release PR is ready, and closes the docs milestone after the merge. Use when preparing a documentation release, before publishing, or when asked to run "pre-release" steps. ---- - -# Pre-release - -Run these steps right before publishing a new documentation release to ensure -release dates are correct and download links point to the latest Memgraph version. - -## When to use - -- Right before merging/publishing the documentation release branch -- When asked to prepare the docs site for a new Memgraph version -- When asked to run "pre-release" tasks - -## Steps - -### 1. Update release note dates - -Open `pages/release-notes.mdx` and update the dates on the latest release -headings to today's date. - -- Look for headings like `### Memgraph v - ` and - `### Lab v - ` near the top of the file (under - "🚀 Latest release"). -- Replace the date with today's date in the same format - (e.g. `May 6th, 2026` → `May 13th, 2026`). -- Only update entries for the version being released. - -### 2. Update direct download links - -Open `pages/getting-started/install-memgraph/direct-download-links.mdx` and -replace **every** occurrence of the previous version with the new one. - -- The file contains download URLs for Docker, CentOS, Debian, Fedora, Rocky, - Red Hat, and Ubuntu packages. -- Two patterns need updating: - - Path segments: `v` → `v` (e.g. `v3.8.1` → `v3.9.0`) - - File names: `` → `` (e.g. `3.8.1` → `3.9.0`) -- Use a global find-and-replace of the bare old version string (e.g. `3.8.1` → - `3.9.0`) — this covers both patterns in a single pass. -- Verify the result: every URL in the file should reference only the new - version. - -### 3. Check the release PR is ready - -- Run `pnpm check` on the release branch; it checks links, redirects, the - sidebar and that each release-note heading loads the matching version. -- Every item on the release PR's Docs Integration Tracking checklist is - ticked, and the docs milestone has no open PRs other than the release PR. - If anything is left, run the `check-release-milestone` skill. - -### 4. After the release PR is merged - -Close the docs milestone. If PRs are still open in it, ask the user whether -to move them to the next release's milestone first. - -```bash -gh api repos/memgraph/documentation/milestones/ \ - --method PATCH -f state=closed -``` From a0dccf2a6b181b4fd7e0d435613ea91e83afe491 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 12:53:46 +0200 Subject: [PATCH 12/18] Keep the release overview in the release PR, rebuilt by check-release The release PR keeps the Docs Integration Tracking checklist between markers. check-release rebuilds it from the labels and milestones on every run and ticks items from what is merged and in the release notes, so nobody edits it by hand. --- skills/check-release/SKILL.md | 78 ++++++++++++++++++++++++++---- skills/new-release-branch/SKILL.md | 14 ++++-- 2 files changed, 80 insertions(+), 12 deletions(-) diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md index c848c26a8..7d2080d0a 100644 --- a/skills/check-release/SKILL.md +++ b/skills/check-release/SKILL.md @@ -1,14 +1,15 @@ --- name: check-release -description: Find what a Memgraph documentation release still needs, and on release day finish it. Checks the docs labels on every merged PR in the Memgraph milestone, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. +description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Checks the docs labels on every merged PR in the Memgraph milestone, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. --- # Check release Works out what a release still needs from GitHub itself — the Memgraph milestone, the docs labels on its PRs, the docs milestone and the release -branch — so nothing has to be tracked by hand. Run it as often as needed -while the release is in progress. On release day, run it once more and +branch — and writes the result as the overview in the release PR +description, so nobody tracks it by hand. Run it as often as needed while +the release is in progress. On release day, run it once more and finish with the release-day steps. Writing quality is not checked here: docs PRs follow the `write-docs-page` @@ -131,7 +132,65 @@ On the release branch, run `pnpm check` (links, section links, redirects, sidebar, release-note versions). Fix what it reports in the release notes; report problems in other pages to the docs PR that introduced them. -### 7. Report +### 7. Update the overview in the release PR + +The release PR description holds the release overview between two markers. +This skill is the only thing that writes between them: rebuild the block +from steps 1–5 on every run, and leave everything outside the markers as it +is. If the description has no markers yet, add the block at the end; if it +has an older hand-kept "Docs Integration Tracking" section, replace that +section with the block. + +~~~ + +### Docs Integration Tracking + +Rebuilt by the `check-release` skill on ; edits here are +overwritten. To change what is listed, fix the product PR's docs label. + +#### Breaking changes PRs + +- [x] https://github.com/memgraph/memgraph/pull/NNNN — short title @author + +#### Docs needed (Memgraph PR → Docs PR) + +- [x] https://github.com/memgraph/memgraph/pull/NNNN → https://github.com/memgraph/documentation/pull/MMMM @author +- [ ] https://github.com/memgraph/memgraph/pull/NNNN → no doc PR yet @author + +#### Changelog (all PRs requiring a changelog entry) + +- [ ] https://github.com/memgraph/memgraph/pull/NNNN @author + +#### Missing docs labels + +- [ ] https://github.com/memgraph/memgraph/pull/NNNN @author + +~~~ + +What goes in each section, in ascending PR number order: + +- **Breaking changes PRs:** merged PRs labeled `breaking`. Ticked when the + entry is under the Breaking changes heading in the release notes. +- **Docs needed:** merged PRs labeled `Docs needed`, with their docs PR (or + `no doc PR yet`). Ticked when the docs PR is merged. A product PR with + several docs PRs lists all of them; tick it when all are merged. +- **Changelog:** merged PRs labeled `Docs needed` or `Docs - changelog only`. + This deliberately repeats the `Docs needed` PRs: it tracks the release + note apart from the docs page. Ticked when the entry is in the release + notes. +- **Missing docs labels:** merged PRs with no docs label. Leave the section + out when there are none. + +Write the description with `gh api`, not `gh pr edit` (which can fail on +this repo): + +```bash +gh api repos/memgraph/documentation/pulls/ --jq .body > body.md +# replace the block between the markers in body.md +gh api repos/memgraph/documentation/pulls/ -X PATCH -F body=@body.md +``` + +### 8. Report Sort every PR list by PR number ascending, and skip sections with nothing to report: @@ -145,21 +204,22 @@ report: - **Docs milestone:** PRs added to it, PRs in it with the wrong base. - **Site checks:** what `pnpm check` reported and what was fixed. -If every section is empty, say the release is ready. +Link the release PR so the user can see the updated overview. If every +section is empty, say the release is ready. ## Release day -Run these only when the user says it's release day, after steps 1–7 report +Run these only when the user says it's release day, after steps 1–8 report the release ready. -### 8. Set the release dates +### 9. Set the release dates In `pages/release-notes.mdx`, set the date on the release's `### Memgraph v - ` heading (and its `### Lab v - ` heading, if Lab ships with it) to today, in the same format (e.g. `May 6th, 2026` → `May 13th, 2026`). -### 9. Update the direct download links +### 10. Update the direct download links In `pages/getting-started/install-memgraph/direct-download-links.mdx`, replace **every** occurrence of the previous version with the new one. @@ -173,7 +233,7 @@ replace **every** occurrence of the previous version with the new one. Run `pnpm check` again, then commit and push to the release branch. -### 10. After the release PR is merged +### 11. After the release PR is merged Close the docs milestone. If PRs are still open in it, ask the user whether to move them to the next release's milestone first. diff --git a/skills/new-release-branch/SKILL.md b/skills/new-release-branch/SKILL.md index 45e9ef4af..9da968e3d 100644 --- a/skills/new-release-branch/SKILL.md +++ b/skills/new-release-branch/SKILL.md @@ -16,7 +16,8 @@ PRs for the release have a branch and a milestone to target: - the release branch `release/` - the docs milestone `` - the release-notes titles on that branch -- the release PR, in the docs milestone +- the release PR, in the docs milestone, with an empty overview block for + `check-release` to fill - a `DOCS ->` link from the Memgraph milestone to the release PR The `write-docs-page` skill opens docs PRs on this branch and milestone and @@ -190,10 +191,17 @@ Milestones Run the `check-release` skill to see what the release still needs; run it with "release day" before merging. + + +### Docs Integration Tracking + +Not built yet: run the `check-release` skill. + ~~~ -The PR keeps no checklist of product PRs: `check-release` works out what is -missing from the Memgraph milestone, its docs labels and the docs milestone. +`check-release` fills the block between the markers with the release +overview (breaking changes, docs PRs, release notes) from the Memgraph +milestone and its docs labels. Don't edit the block by hand. ## Step 7 — Link the release PR from the Memgraph milestone From b3c86957042c5b4280d3787cc8ed9adcb9626646 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 13:01:19 +0200 Subject: [PATCH 13/18] Write release notes from the docs PR's release note corrections write-changelog-item reads the corrections the writing skill lists for a series of product PRs, and check-release points to them from the overview. check-release also skips the release PR when matching docs PRs to product PRs. --- skills/check-release/SKILL.md | 13 +++++++++++-- skills/write-changelog-item/SKILL.md | 10 ++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md index 7d2080d0a..b94af260c 100644 --- a/skills/check-release/SKILL.md +++ b/skills/check-release/SKILL.md @@ -112,6 +112,10 @@ gh pr list --repo memgraph/documentation --state all --search "milestone:`): it names every PR in + the release. +- Note the docs PRs whose description has a `### Release note corrections` + section, and which product PRs it lists. The overview points to them. - Every merged PR labeled `Docs needed` has a docs PR. If none names it, check the product PR's "Documentation PR link" comment (`gh api repos/memgraph/memgraph/issues//comments`) before calling it @@ -160,6 +164,7 @@ overwritten. To change what is listed, fix the product PR's docs label. #### Changelog (all PRs requiring a changelog entry) - [ ] https://github.com/memgraph/memgraph/pull/NNNN @author +- [ ] https://github.com/memgraph/memgraph/pull/NNNN @author ⚠ corrections in memgraph/documentation#MMMM #### Missing docs labels @@ -177,7 +182,9 @@ What goes in each section, in ascending PR number order: - **Changelog:** merged PRs labeled `Docs needed` or `Docs - changelog only`. This deliberately repeats the `Docs needed` PRs: it tracks the release note apart from the docs page. Ticked when the entry is in the release - notes. + notes. When a docs PR lists release note corrections for the product PR, + end the line with `⚠ corrections in memgraph/documentation#MMMM`, so + whoever writes the entry starts from them. - **Missing docs labels:** merged PRs with no docs label. Leave the section out when there are none. @@ -198,7 +205,9 @@ report: - **Docs labels:** missing or questionable labels, the recommended label and a one-line reason. - **Release notes:** PRs with no entry, breaking changes outside the Breaking - section, `Docs needed` entries with no docs link. + section, `Docs needed` entries with no docs link, and docs PRs with release + note corrections for entries already written (check the entry follows + them). - **Docs PRs:** `Docs needed` PRs with no docs PR (with the author's `@handle`), and open docs PRs. - **Docs milestone:** PRs added to it, PRs in it with the wrong base. diff --git a/skills/write-changelog-item/SKILL.md b/skills/write-changelog-item/SKILL.md index 11b1a4c40..44703d720 100644 --- a/skills/write-changelog-item/SKILL.md +++ b/skills/write-changelog-item/SKILL.md @@ -62,6 +62,16 @@ no link. Usually the PR has the item written in one of the comments under the PR. Try to extract that first and improve according to the above description. +Then read the docs PR that covers the product PR: the open or merged one +whose description names it as `memgraph/memgraph#NNNN`, not the release PR +(titled `Memgraph v`) and not one closed without merging. Its +`### Release note corrections` section lists, for the whole series of +product PRs, where the release note is wrong or misses something, checked +against the build after the last PR in the series. Where it disagrees with +the comment, follow the docs PR. An older docs PR without that section may +still note release-note problems in its description; read them the same +way. + If that changelog item is not already there, feel free to create one, again according to the above guidelines. From 666d291a681c4eb34d1595f650ec01abc0d9693a Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 13:02:41 +0200 Subject: [PATCH 14/18] Show how much of the Memgraph milestone is merged in check-release The overview starts with a Progress section: merged out of open and merged PRs, overall and for PRs that need docs or a release note, so it's clear how much docs work can be done now and how much has to wait. --- skills/check-release/SKILL.md | 40 +++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md index b94af260c..092b813da 100644 --- a/skills/check-release/SKILL.md +++ b/skills/check-release/SKILL.md @@ -1,6 +1,6 @@ --- name: check-release -description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Checks the docs labels on every merged PR in the Memgraph milestone, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. +description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. --- # Check release @@ -50,14 +50,28 @@ From the version or Memgraph milestone the user gives (e.g. `mg-v3.15.0`): If the branch, the docs milestone or the release PR is missing, the release hasn't been started: run the `new-release-branch` skill first. -Fetch every merged PR in the Memgraph milestone once and reuse it below: +Fetch every PR in the Memgraph milestone once and reuse it below: ```bash -gh api --paginate "repos/memgraph/memgraph/issues?milestone=&state=closed&per_page=100" \ - --jq '.[] | select(.pull_request != null and .pull_request.merged_at != null) | - {number, title, author: .user.login, labels: [.labels[].name]}' +gh api --paginate "repos/memgraph/memgraph/issues?milestone=&state=all&per_page=100" \ + --jq '.[] | select(.pull_request != null) | + {number, title, author: .user.login, labels: [.labels[].name], + status: (if .pull_request.merged_at then "merged" + elif .state == "open" then (if .draft then "draft" else "open" end) + else "closed" end)}' ``` +Steps 2–5 use the merged PRs only. Open and draft PRs count only toward +progress; PRs closed without merging are left out entirely. + +**Progress:** how much of the Memgraph milestone is merged, which tells how +much docs work can be done now and how much has to wait: + +- **All PRs:** merged out of merged + open + draft, as a percentage. +- **Docs work:** the same for PRs labeled `Docs needed` or + `Docs - changelog only`, split by label: merged ones can be documented + now, open and draft ones can't yet. + ### 2. Docs labels Classify each merged PR: @@ -152,6 +166,16 @@ section with the block. Rebuilt by the `check-release` skill on ; edits here are overwritten. To change what is listed, fix the product PR's docs label. +#### Progress + +Memgraph milestone: 166 of 217 PRs merged (76%); 29 open, 22 draft. + +| Docs work | Merged (can be done now) | Open or draft (waiting) | +| --- | --- | --- | +| Docs needed | 17 | 10 | +| Docs - changelog only | 53 | 24 | +| **Total** | **70 of 104 (67%)** | **34** | + #### Breaking changes PRs - [x] https://github.com/memgraph/memgraph/pull/NNNN — short title @author @@ -172,7 +196,10 @@ overwritten. To change what is listed, fix the product PR's docs label. ~~~ -What goes in each section, in ascending PR number order: +What goes in each section, in ascending PR number order (the numbers in +Progress are an example): + +- **Progress:** from step 1, counted fresh on every run. - **Breaking changes PRs:** merged PRs labeled `breaking`. Ticked when the entry is under the Breaking changes heading in the release notes. @@ -202,6 +229,7 @@ gh api repos/memgraph/documentation/pulls/ -X PATCH -F body=@body.md Sort every PR list by PR number ascending, and skip sections with nothing to report: +- **Progress:** the step 1 numbers, as in the overview. - **Docs labels:** missing or questionable labels, the recommended label and a one-line reason. - **Release notes:** PRs with no entry, breaking changes outside the Breaking From 8e888b12559449f8a03ab6c74aa1e69563a2975e Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Tue, 13 Oct 2026 13:22:08 +0200 Subject: [PATCH 15/18] Fix the problems docs PRs noticed in one PR per release check-release collects the Noticed, not fixed items from the release's docs PRs, lists them in the overview, and fixes them in one PR into the release branch. The docs PR template has both sections the release check reads, each with a note to keep its heading and format. --- .github/pull_request_template.md | 12 +++++++ AGENTS.md | 2 ++ skills/check-release/SKILL.md | 55 ++++++++++++++++++++++++++------ 3 files changed, 59 insertions(+), 10 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5b6cdee46..88899ff8e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,3 +10,15 @@ - [ ] For a product change: milestone set to the release and `feature` or `bugfix` label added - [ ] For a product change: this PR is linked from the product PR's documentation checklist + +### Release note corrections + +_Read by the release check when the release notes are written. Fix an item if it's wrong; keep the heading and one line per product PR. Delete the section if it's empty._ + + + +### Noticed, not fixed + +_Read by the release check, which fixes these in one PR per release. Fix an item if it's wrong; keep the heading and one line per item, starting with the page. Delete the section if it's empty._ + + diff --git a/AGENTS.md b/AGENTS.md index f79902163..11a4165cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,6 +43,8 @@ The short version, for everyone: needs and, on release day, finishes it. - Use `.github/pull_request_template.md` and name the product PR as `memgraph/memgraph#NNNN`. +- Keep the headings and line format of "Release note corrections" and + "Noticed, not fixed" in a docs PR description: `check-release` reads them. ## Run locally diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md index 092b813da..826e537a7 100644 --- a/skills/check-release/SKILL.md +++ b/skills/check-release/SKILL.md @@ -1,6 +1,6 @@ --- name: check-release -description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. +description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`, and fixes the problems docs PRs noticed in one PR per release; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. --- # Check release @@ -130,6 +130,10 @@ gh pr list --repo memgraph/documentation --state all --search "milestone:/comments`) before calling it @@ -144,17 +148,39 @@ gh pr list --repo memgraph/documentation --state all --search "milestone:`; flag the others. - The release PR is in the docs milestone. -### 6. Site checks +### 6. Noticed problems + +Docs PRs list broken things they noticed outside their own change under +`### Noticed, not fixed`. Fix them all in one PR per release, into the +release branch so the fixes don't conflict with the release's own changes. + +- **When:** once most docs PRs for the release are merged, and at the latest + before release day. Ask the user before opening the PR; until then, only + list the items. +- **Find the PR:** it uses the branch `docs/-noticed-fixes`. If it + exists, add new items to it instead of opening another. +- **Skip** items already fixed on the release branch (read the page there). +- **Fix** each remaining item following the `write-docs-page` skill's + rules, keeping each fix to the item: no reformatting of the rest of the + page. Re-run any Cypher example you change on a build with the release's + changes, such as the newest daily build. +- **Open** the PR as a draft into `release/`, in the docs milestone, + with no label, titled "Fix problems noticed while writing the + docs". Fill the body from `.github/pull_request_template.md` with "none" + as the product PR, and list every item with the docs PR it came from. + Items you couldn't fix stay listed with the reason. + +### 7. Site checks On the release branch, run `pnpm check` (links, section links, redirects, sidebar, release-note versions). Fix what it reports in the release notes; report problems in other pages to the docs PR that introduced them. -### 7. Update the overview in the release PR +### 8. Update the overview in the release PR The release PR description holds the release overview between two markers. This skill is the only thing that writes between them: rebuild the block -from steps 1–5 on every run, and leave everything outside the markers as it +from steps 1–6 on every run, and leave everything outside the markers as it is. If the description has no markers yet, add the block at the end; if it has an older hand-kept "Docs Integration Tracking" section, replace that section with the block. @@ -193,6 +219,10 @@ Memgraph milestone: 166 of 217 PRs merged (76%); 29 open, 22 draft. #### Missing docs labels - [ ] https://github.com/memgraph/memgraph/pull/NNNN @author + +#### Noticed, not fixed + +- [ ] `pages/.mdx`: what's wrong — from memgraph/documentation#MMMM ~~~ @@ -214,6 +244,9 @@ Progress are an example): whoever writes the entry starts from them. - **Missing docs labels:** merged PRs with no docs label. Leave the section out when there are none. +- **Noticed, not fixed:** the items from step 6. Ticked when the + noticed-fixes PR that fixes them is merged; an item it couldn't fix ends + with the reason. Leave the section out when there are none. Write the description with `gh api`, not `gh pr edit` (which can fail on this repo): @@ -224,7 +257,7 @@ gh api repos/memgraph/documentation/pulls/ --jq .body > body.md gh api repos/memgraph/documentation/pulls/ -X PATCH -F body=@body.md ``` -### 8. Report +### 9. Report Sort every PR list by PR number ascending, and skip sections with nothing to report: @@ -239,6 +272,8 @@ report: - **Docs PRs:** `Docs needed` PRs with no docs PR (with the author's `@handle`), and open docs PRs. - **Docs milestone:** PRs added to it, PRs in it with the wrong base. +- **Noticed problems:** items found, and the noticed-fixes PR (or that it + hasn't been opened yet). - **Site checks:** what `pnpm check` reported and what was fixed. Link the release PR so the user can see the updated overview. If every @@ -246,17 +281,17 @@ section is empty, say the release is ready. ## Release day -Run these only when the user says it's release day, after steps 1–8 report -the release ready. +Run these only when the user says it's release day, after steps 1–9 report +the release ready, including a merged noticed-fixes PR (step 6). -### 9. Set the release dates +### 10. Set the release dates In `pages/release-notes.mdx`, set the date on the release's `### Memgraph v - ` heading (and its `### Lab v - ` heading, if Lab ships with it) to today, in the same format (e.g. `May 6th, 2026` → `May 13th, 2026`). -### 10. Update the direct download links +### 11. Update the direct download links In `pages/getting-started/install-memgraph/direct-download-links.mdx`, replace **every** occurrence of the previous version with the new one. @@ -270,7 +305,7 @@ replace **every** occurrence of the previous version with the new one. Run `pnpm check` again, then commit and push to the release branch. -### 11. After the release PR is merged +### 12. After the release PR is merged Close the docs milestone. If PRs are still open in it, ask the user whether to move them to the next release's milestone first. From 163ea6abbc12ca783af4d77252d95a6f4e8e3eaa Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Wed, 21 Oct 2026 14:40:41 +0200 Subject: [PATCH 16/18] Flag docs for product PRs outside the milestone and gate the release on the examples check in check-release --- skills/check-release/SKILL.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md index 826e537a7..f899b4e39 100644 --- a/skills/check-release/SKILL.md +++ b/skills/check-release/SKILL.md @@ -1,6 +1,6 @@ --- name: check-release -description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR, the docs milestone and `pnpm check`, and fixes the problems docs PRs noticed in one PR per release; on release day also sets the release dates, updates the direct download links and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. +description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR (and no docs for product PRs outside the milestone), the docs milestone and `pnpm check`, and fixes the problems docs PRs noticed in one PR per release; on release day also sets the release dates, updates the direct download links, gets the release PR's examples check passing and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. --- # Check release @@ -138,6 +138,10 @@ gh pr list --repo memgraph/documentation --state all --search "milestone:/comments`) before calling it missing. +- Every product PR a docs PR names is merged and in this Memgraph milestone. + A docs PR can cover several product PRs, and one of them may move to a + later release. Its content then documents a feature that doesn't ship: + move that part to a new docs PR in the next release's docs milestone. - Open docs PRs still block the release. ### 5. Docs milestone @@ -270,11 +274,13 @@ report: note corrections for entries already written (check the entry follows them). - **Docs PRs:** `Docs needed` PRs with no docs PR (with the author's - `@handle`), and open docs PRs. + `@handle`), open docs PRs, and docs PRs that name a product PR not merged + in this milestone (with that PR's milestone). - **Docs milestone:** PRs added to it, PRs in it with the wrong base. - **Noticed problems:** items found, and the noticed-fixes PR (or that it hasn't been opened yet). -- **Site checks:** what `pnpm check` reported and what was fixed. +- **Site checks:** what `pnpm check` reported and what was fixed. On + release day, also the release PR's `Examples and names` result. Link the release PR so the user can see the updated overview. If every section is empty, say the release is ready. @@ -305,6 +311,13 @@ replace **every** occurrence of the previous version with the new one. Run `pnpm check` again, then commit and push to the release branch. +Before the release PR is merged, its `Examples and names` CI job must pass. +It runs the Cypher examples the release changes on the new version's image, +so it can only pass once that image is published; rerun it then. Fix what it +reports on the release branch: a block that isn't meant to run gets a fence +mark (` ```cypher invalid `, `template`, `neo4j` or `output`), and a real +broken example goes back to the docs PR that introduced it. + ### 12. After the release PR is merged Close the docs milestone. If PRs are still open in it, ask the user whether From ef5fb1b54bafc37d80a947d08e1aebccc34e4b18 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Wed, 21 Oct 2026 14:45:27 +0200 Subject: [PATCH 17/18] Cover patch releases during an open minor release, describe the behavior that ships, and tidy write-changelog-item --- scripts/check-docs.mjs | 9 ++++++++- skills/new-release-branch/SKILL.md | 6 ++++++ skills/write-changelog-item/SKILL.md | 29 +++++++++++----------------- 3 files changed, 25 insertions(+), 19 deletions(-) diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index 626779863..04d6dd1b7 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -1,7 +1,8 @@ /** * Checks the docs source for things that break for readers: links to pages or * sections that don't exist, links through a redirect, broken redirects, pages - * missing from the sidebar, missing images and mismatched release-note versions. + * missing from the sidebar, missing images, mismatched release-note versions and + * repeated release-note sections. * * It reads only this checkout (no build, no network) and runs in a few seconds. * Any problem fails the check. The rules are the ones in AGENTS.md. @@ -325,8 +326,14 @@ const NOTES = path.join(PAGES, 'release-notes.mdx') if (fs.existsSync(NOTES)) { const lines = text.get(NOTES).split('\n') const seen = new Map() + const sections = new Map() let current = null lines.forEach((line, i) => { + const s = line.match(/^##\s+(.+?)\s*$/) + if (s) { + if (sections.has(s[1])) report(NOTES, i + 1, `"## ${s[1]}" appears twice (also on line ${sections.get(s[1])})`) + else sections.set(s[1], i + 1) + } const h = line.match(/^#{2,4}\s+(.+?)\s+v(\d+\.\d+\.\d+)\b/) if (h) { current = { product: h[1].trim(), version: h[2], line: i + 1 } diff --git a/skills/new-release-branch/SKILL.md b/skills/new-release-branch/SKILL.md index 9da968e3d..00838a589 100644 --- a/skills/new-release-branch/SKILL.md +++ b/skills/new-release-branch/SKILL.md @@ -105,6 +105,12 @@ Insert the new Memgraph title immediately after the line The patch stays under "Latest release" with the minor release it patches. Add a Lab title only if Lab ships with this patch. +If the next minor release branch is already open, its release notes have +moved the patched minor under `## Previous releases`. When `main` is merged +into that branch after the patch ships, put the patch heading there, above +the minor it patches, and keep a single `## Previous releases` heading. +`pnpm check` fails on a repeated `##` section. + ### Minor release Make **two** changes: diff --git a/skills/write-changelog-item/SKILL.md b/skills/write-changelog-item/SKILL.md index 44703d720..abb7cf665 100644 --- a/skills/write-changelog-item/SKILL.md +++ b/skills/write-changelog-item/SKILL.md @@ -3,21 +3,13 @@ name: write-changelog-item description: Create/write the changelog item / release note for a given Github PR in `pages/release-notes.mdx` on the release branch. Use when asked to write a release note or changelog entry, or when `check-release` finds a PR missing from the release notes. --- -For a given Github PR write a changelog item. - -## Listing PRs - -When you present more than one PR to the user (missing changelog queue, docs -gaps, suggested next item with alternatives, etc.), always sort by PR number -**ascending** (smallest → largest). +Writes one release note for a Memgraph PR. When listing several PRs, sort +them by PR number ascending. ## Writing the changelog item Release notes and any related documentation must be **user friendly and -user-centric**. - -We are not describing the engineering work we did, but the impact the user -sees. +user-centric**: describe the impact the user sees, not the engineering work. Write for someone who runs Memgraph, writes Cypher, operates a cluster, or authors modules — not for someone reading the PR diff. Prefer: @@ -47,9 +39,8 @@ Avoid: - Second-person or first-person address ("you get a warning", "you can now", "we fixed"). State the behavior without naming the reader. -The changelog item should be benefit focused (highlight the why). The changelog -item should be in the markdown format, don't remove ticks and markdown links, -don't use bold and italic, use - at the beginning of the item. +Lead with the benefit. Write the item as one Markdown bullet starting with +`-`: keep code ticks and links, and use no bold or italic. Link the docs page for the change in the item whenever there is one: the page from the docs PR for a **Docs needed** PR, or the existing page that covers the @@ -59,8 +50,11 @@ Readers and agents look at the release notes first to learn what changed; the link takes them to how it works now. A bug fix with no page to point to needs no link. -Usually the PR has the item written in one of the comments under the PR. Try to -extract that first and improve according to the above description. +Start from the release note in the product PR's comments, if there is one, +and improve it by the rules above. The PR description and that note describe +the PR as it was opened. If a later PR in the same series (one stacked on it +or changing the same behavior) changed what users see, describe the behavior +that ships: read the later PRs, or the code at the release tag. Then read the docs PR that covers the product PR: the open or merged one whose description names it as `memgraph/memgraph#NNNN`, not the release PR @@ -72,8 +66,7 @@ the comment, follow the docs PR. An older docs PR without that section may still note release-note problems in its description; read them the same way. -If that changelog item is not already there, feel free to create one, again -according to the above guidelines. +If the product PR has no release note, write one by the same rules. If the PR introduces a breaking change, put it **only** under the Breaking section — do not also list it under New features, Improvements, or Bug fixes. From 1f5a340a25c7305b5fc47f9020f435933635a782 Mon Sep 17 00:00:00 2001 From: katarinasupe Date: Wed, 21 Oct 2026 14:48:59 +0200 Subject: [PATCH 18/18] Create the docs GitHub release after the release PR is merged in check-release --- skills/check-release/SKILL.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/skills/check-release/SKILL.md b/skills/check-release/SKILL.md index f899b4e39..87bf5d2fd 100644 --- a/skills/check-release/SKILL.md +++ b/skills/check-release/SKILL.md @@ -1,6 +1,6 @@ --- name: check-release -description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR (and no docs for product PRs outside the milestone), the docs milestone and `pnpm check`, and fixes the problems docs PRs noticed in one PR per release; on release day also sets the release dates, updates the direct download links, gets the release PR's examples check passing and closes the docs milestone after the merge. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. +description: Find what a Memgraph documentation release still needs, keep the overview in the release PR up to date, and on release day finish the release. Reports how much of the Memgraph milestone is merged, checks the docs labels on every merged PR in it, release notes for every PR that needs one, a docs PR for every "Docs needed" PR (and no docs for product PRs outside the milestone), the docs milestone and `pnpm check`, and fixes the problems docs PRs noticed in one PR per release; on release day also sets the release dates, updates the direct download links, gets the release PR's examples check passing, and after the merge creates the GitHub release and closes the docs milestone. Use while a release is in progress, before merging a release branch into main, or when asked to "check the release", "check before release", run "pre-release" steps or audit docs labels on a milestone. --- # Check release @@ -320,8 +320,22 @@ broken example goes back to the docs PR that introduced it. ### 12. After the release PR is merged -Close the docs milestone. If PRs are still open in it, ask the user whether -to move them to the next release's milestone first. +Create the GitHub release for the docs at the release PR's merge commit. The +tag is `v` (`v3.15`, `v3.13.2`), the title `Docs for Memgraph +`, and the notes start from the previous release's tag: + +```bash +gh release list --repo memgraph/documentation --limit 1 # previous tag +gh release create v --repo memgraph/documentation \ + --target --title "Docs for Memgraph " \ + --generate-notes --notes-start-tag +``` + +A patch of an older minor (a `3.13.3` after `3.14` is out) adds +`--latest=false`. + +Then close the docs milestone. If PRs are still open in it, ask the user +whether to move them to the next release's milestone first. ```bash gh api repos/memgraph/documentation/milestones/ \