check-before-release

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.

Check before release

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.

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, canvas 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=<id>&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 <number> --repo memgraph/memgraph --json title,body,labels,author
     

   • Produce a canvas (read and follow ~/.cursor/skills-cursor/canvas/SKILL.md) showing:
     • 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 ().

References

• Canvas skill: ~/.cursor/skills-cursor/canvas/SKILL.md — required for producing the label audit canvas in step 1.
• 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
• 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.
• 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=<id>&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.