diff --git a/docs.json b/docs.json
index 37e3fce6..8f3dbefd 100644
--- a/docs.json
+++ b/docs.json
@@ -44,9 +44,7 @@
"tabs": [
{
"tab": "Overview",
- "pages": [
- "index"
- ]
+ "pages": ["index"]
},
{
"tab": "Merge Queue",
@@ -124,9 +122,7 @@
},
{
"group": "Metrics Endpoints",
- "pages": [
- "GET /getMergeQueueMetrics"
- ]
+ "pages": ["GET /getMergeQueueMetrics"]
},
{
"group": "Queue Endpoints",
@@ -153,7 +149,8 @@
"root": "merge-queue/reference/index",
"pages": [
"merge-queue/reference/common-problems",
- "merge-queue/reference/troubleshooting"
+ "merge-queue/reference/troubleshooting",
+ "merge-queue/reference/github-api-failures"
]
},
"merge-queue/changelog"
@@ -170,9 +167,7 @@
{
"group": "Overview",
"root": "flaky-tests/overview",
- "pages": [
- "flaky-tests/dashboard"
- ]
+ "pages": ["flaky-tests/dashboard"]
},
{
"group": "Getting Started",
@@ -304,9 +299,7 @@
},
{
"group": "Recipes",
- "pages": [
- "flaky-tests/recipes/alert-on-test-escalation"
- ]
+ "pages": ["flaky-tests/recipes/alert-on-test-escalation"]
},
{
"group": "Agents",
@@ -726,9 +719,7 @@
},
{
"group": "October",
- "pages": [
- "changelog/2025-10-09-plugins-1-7-3"
- ]
+ "pages": ["changelog/2025-10-09-plugins-1-7-3"]
},
{
"group": "September",
@@ -1016,12 +1007,7 @@
}
},
"contextual": {
- "options": [
- "copy",
- "view",
- "chatgpt",
- "claude"
- ]
+ "options": ["copy", "view", "chatgpt", "claude"]
},
"footer": {
"socials": {
diff --git a/merge-queue/getting-started/index.mdx b/merge-queue/getting-started/index.mdx
index 783c7c35..00a4515d 100644
--- a/merge-queue/getting-started/index.mdx
+++ b/merge-queue/getting-started/index.mdx
@@ -99,7 +99,7 @@ If your test PR doesn't merge automatically:
- **Check the status comments for the PR in** the [Trunk Dashboard](https://app.trunk.io/) to see what it's waiting for
- **Stuck in "Queued"**: Usually means branch protection rules haven't passed (missing required status checks or code review) or there are merge conflicts. If the status looks correct but the PR still won't enter the queue, try [removing](../using-the-queue/reference#submitting-and-cancelling-pull-requests) and re-adding by commenting `/trunk merge` again on the PR.
-- **Fails when attempting to merge**: Check that squash merges are enabled for your repository in GitHub settings (`Settings > General > Allow squash merging`). Trunk Merge Queue requires squash merges to be enabled.
+- **Fails when attempting to merge**: Check that the [merge method](/merge-queue/administration/advanced-settings#merge-method) your queue is configured to use (squash by default) is enabled for your repository in GitHub settings (`Settings > General`).
- **"Permission denied" errors**: Review the [Branch Protection](./configure-branch-protection) guide to make sure `trunk-temp/*` and `trunk-merge/*` branches aren't protected by wildcard rules like `*/*`.
- **Status checks not running**: Verify your CI is configured to run on draft PRs (or `trunk-merge/**` branches if using push-triggered mode). See the [Branch Protection](./configure-branch-protection) guide for details.
diff --git a/merge-queue/reference/common-problems.mdx b/merge-queue/reference/common-problems.mdx
index 1d76332a..25e105f9 100644
--- a/merge-queue/reference/common-problems.mdx
+++ b/merge-queue/reference/common-problems.mdx
@@ -13,6 +13,7 @@ og:title: "Trunk Merge Queue FAQ"
First, check the Trunk web app to see what Trunk is waiting on before putting your PR into the merge queue.
Next, if something on that page doesn't look right, for example, it says that GitHub is still checking the mergeability of the PR, comment `/trunk merge` again in the PR.
+
@@ -33,6 +34,7 @@ og:title: "Trunk Merge Queue FAQ"
**Note:** The merge method applies to the entire repository, not on a per-PR basis. See [Merge Method documentation](/merge-queue/administration/advanced-settings#merge-method) for detailed information on each option and how to configure your preference.
+
@@ -45,6 +47,7 @@ og:title: "Trunk Merge Queue FAQ"
You can override the merge commit title for any PR by adding `merge-commit-title: Your Custom Title` on its own line in the PR body. See the FAQ below for details.
You can configure your preferred merge method in [Advanced Settings](../administration/advanced-settings#merge-method).
+
@@ -63,9 +66,10 @@ og:title: "Trunk Merge Queue FAQ"
```markdown
## Description
This PR adds user authentication.
-
+
merge-commit-title: feat(auth): add OAuth2 login flow [PROJ-123]
```
+
@@ -75,6 +79,7 @@ og:title: "Trunk Merge Queue FAQ"
- [Optimistic Merging](../optimizations/optimistic-merging) uses the successful test of a pull request later in the queue to validate all the PRs ahead of it in the queue, allowing the entire sequence to be merged without waiting for the earlier PRs to finish testing.
- [Batching](../optimizations/batching) allows the queue to _test_ multiple PRs in a single CI job to save time and resources. After the test passes, the PRs in the batch are still merged one by one.
+
@@ -85,12 +90,14 @@ og:title: "Trunk Merge Queue FAQ"
To create an additional queue, click **New Queue** from the Merge Queue dashboard and select the same repository with a different target branch. See [Multiple queues per repository](../administration/advanced-settings#multiple-queues-per-repository) for details.
For validating significant changes to your CI process or queue configuration without impacting your primary workflow, you can use a fork of your repository. Set up and test a separate merge queue on the fork to make sure your changes work as expected before applying them to your primary repository.
+
No, you should configure your CI to completely ignore `trunk-temp/*` branches. Running workflows on them will only create unnecessary or canceled builds.
The `trunk-temp/*` branch is a temporary, intermediate branch that the merge queue uses to assemble the necessary commits for a test run. Once the build is prepared, this branch is immediately renamed to a `trunk-merge/*` branch.
+
@@ -103,6 +110,7 @@ og:title: "Trunk Merge Queue FAQ"
```
The `urgent` priority is the only level that will interrupt currently testing PRs. Your PR will immediately begin testing, and other PRs will restart after yours completes.
+
@@ -113,6 +121,7 @@ og:title: "Trunk Merge Queue FAQ"
```
The `urgent` priority is the only level that will interrupt currently testing PRs. Your PR will immediately begin testing, and other PRs will restart after yours completes.
+
@@ -123,22 +132,29 @@ og:title: "Trunk Merge Queue FAQ"
+
Most likely, you have a [branch protection rule](../getting-started/configure-branch-protection) that affects merge branches.
For example, the wild card rule `*/*` applies to `trunk-merge/...`. The Trunk GitHub app does not have admin privileges, so it fails to do some actions on protected branches. To resolve this, you must remove this rule or contact [support@trunk.io](mailto:support@trunk.io) if that is not possible.
-
-
- The two most likely problems are that you are restricting **who can merge** or that you have **disabled squash merges** into your repo. Trunk Merge Queue needs to use squash merges. To fix this, turn on `'allow squash merges'` for this repo in your GitHub setup.
+
+ The two most likely problems are that you are restricting **who can merge** or
+ that the [merge method](../administration/advanced-settings#merge-method) your
+ queue uses (squash by default) is **disabled in your repo's GitHub settings**.
+ To fix this, enable that merge method under **Settings → General** in GitHub,
+ or configure the queue to use a method your repo allows.
+
+
By default, both [dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#changing-the-rebase-strategy-for-dependabot-pull-requests) and [renovate](https://docs.renovatebot.com/updating-rebasing/#updating-and-rebasing-branches) both will rebase their PRs whenever other PRs merge into their base branch. If that rebase happens when those PRs are in the queue, they will get kicked since they were updated. There are two ways to mitigate this:
1. Both dependabot and renovate can be configured to not automatically rebase, while renovate can specifically be configured to only rebase if there's a merge conflict ([dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#rebase-strategy), [renovate](https://docs.renovatebot.com/configuration-options/#rebasewhen))
2. Their PRs can be manually merged, and anything currently in the merge queue will restart with those merged changes
+
-
\ No newline at end of file
+
diff --git a/merge-queue/reference/github-api-failures.mdx b/merge-queue/reference/github-api-failures.mdx
new file mode 100644
index 00000000..a37246e6
--- /dev/null
+++ b/merge-queue/reference/github-api-failures.mdx
@@ -0,0 +1,90 @@
+---
+title: "GitHub API failures"
+description: "What to do when a PR fails to merge because of GitHub server errors, rate limits, or rejected merge calls."
+og:title: "GitHub API failures in Trunk Merge Queue"
+---
+
+Sometimes a pull request fails in the queue not because of its code or tests, but because of a problem on GitHub's side. When that happens, Trunk Merge Queue removes the PR from the queue and posts a failure message that links to one of the sections below. Each section explains what the message means, what Trunk already tried, and how to get your PR merged.
+
+In most cases the fix is the same: confirm GitHub is healthy at [githubstatus.com](https://www.githubstatus.com), then re-submit the PR the same way you normally enqueue it. See [Handle failed pull requests](/merge-queue/using-the-queue/handle-failed-pull-requests) for all the ways to re-queue a PR.
+
+
+ Visit [Trunk Support](/setup-and-administration/support) for additional
+ assistance or to contact the support team.
+
+
+## GitHub server errors
+
+> GitHub's API repeatedly returned server errors, so it could not be merged.
+
+When Trunk called GitHub's merge API, GitHub responded with server errors (HTTP 500, 502, 503, or 504). These errors come from GitHub's infrastructure, not from your PR or your queue configuration.
+
+Trunk already retried the merge automatically — 10 attempts over roughly 60 seconds — and only declared the failure after every attempt returned a server error.
+
+**To resolve:**
+
+1. Re-submit the PR. This was most likely a brief blip on GitHub's side, and re-submitting usually succeeds.
+2. If it fails again, check [githubstatus.com](https://www.githubstatus.com) for an active incident affecting Pull Requests or the API. If there's an incident, wait for it to resolve before re-submitting.
+3. If GitHub's status is green and the failure keeps happening, contact [help@trunk.io](mailto:help@trunk.io) with a link to the affected PR.
+
+## Merge already in progress
+
+> GitHub repeatedly reported that a merge was already in progress.
+
+GitHub returned HTTP 405 with the message "Merge already in progress" — meaning GitHub considers a merge of _this PR_ to already be underway. This typically starts with GitHub returning a server error (such as a 503) on the first merge attempt; on every retry after that, GitHub reports that the first attempt is still in progress on its side. Trunk retried automatically — 10 attempts over roughly 60 seconds — before declaring the failure.
+
+
+ Even though GitHub reported the merge as failed, **it may have actually merged
+ your PR**. GitHub's answer reflects its state at that moment, and that state
+ can lag behind what actually happened. Before you re-submit, check the base
+ branch's commit history for your PR's commit.
+
+
+This failure can leave your PR in one of three states. To figure out which one you're in, open the base branch's commit history in GitHub (**Code → Commits** on the base branch) and look for a commit referencing your PR number:
+
+**1. The PR is open and your commit is _not_ on the base branch.** The merge genuinely didn't happen. Wait a moment for GitHub to settle, then re-submit the PR. If the queue is empty and you're in a hurry, you can also merge the PR directly in GitHub.
+
+**2. The PR is open but your commit _is_ on the base branch.** GitHub pushed the merge commit even though it reported the merge as failed, and hasn't yet marked the PR as merged. **Do not re-submit** — the change is already in. Either wait for GitHub to catch up and mark the PR merged, or manually close the PR. (A manually closed PR shows as "Closed" rather than "Merged" in GitHub — that's cosmetic; your commit is on the base branch either way.)
+
+**3. The PR shows as closed or merged (possibly only for some viewers).** The merge went through and GitHub's UI is catching up — different people may briefly see different states for the same PR. No action needed; the PR's state will converge on its own.
+
+**If this keeps happening:** contact [help@trunk.io](mailto:help@trunk.io) with a link to the affected PR. This error comes from GitHub's side, and we can raise repeated occurrences with GitHub.
+
+## GitHub error starting tests
+
+> It repeatedly encountered a transient GitHub error.
+
+This failure happens while Trunk is _starting tests_ for your PR, not while merging it. To test a PR, Trunk prepares a test branch through the GitHub API, and those API calls repeatedly hit transient errors. The most common cause is GitHub API rate limiting (HTTP 429 — either the primary rate limit or secondary/concurrency limits); GitHub can also return transient 422 errors during branch preparation. Trunk retried about 3 times over roughly 90 seconds before declaring the failure.
+
+**To resolve:**
+
+1. Wait a few minutes for the rate-limit window to reset, then re-submit the PR. This resolves most cases.
+2. Check [githubstatus.com](https://www.githubstatus.com) to rule out a GitHub incident.
+3. If the failure persists, contact [help@trunk.io](mailto:help@trunk.io) with a link to the affected PR. Rate limits apply org-wide and you can't easily see what's consuming them — we can help figure out whether the queue's own activity, other automation, or something on GitHub's side is responsible.
+
+## GitHub rejected merge
+
+> GitHub returned the following error when attempting to merge it - \.
+
+GitHub rejected the merge for a non-transient reason and returned an error message, which Trunk shows verbatim in the failure. Unlike the failures above, retrying won't help until the underlying cause is fixed. The most common cause is branch protection rules or repository rulesets that aren't satisfied — required approvals, required status checks, or a branch-must-be-up-to-date requirement.
+
+**To resolve:**
+
+1. Read the GitHub error text included in the failure message — it names the specific requirement that wasn't met.
+2. Fix the underlying cause: get the required approvals, make the required checks pass, or update your branch with its base.
+3. Re-submit the PR.
+
+Common GitHub error messages and their fixes:
+
+| GitHub error | What it means | How to fix it |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `At least N approving review(s) is required...` | Branch protection requires more approvals than the PR has, or a new commit dismissed earlier approvals. | Get the required approvals, then re-submit. |
+| `Required status check "..." is expected.` / `...has not succeeded` | A status check required by branch protection is missing or failing on the PR. | Make sure the named check runs and passes on the PR, then re-submit. See [Configure branch protection](/merge-queue/getting-started/configure-branch-protection). |
+| `Base branch was modified. Review and try the merge again.` | The base branch changed between GitHub's mergeability check and the merge call. | Usually transient — re-submit the PR. |
+| `Pull Request is not mergeable` | The PR has merge conflicts, or GitHub hasn't finished computing mergeability. | Resolve any conflicts with the base branch, then re-submit. |
+| `Squash merges are not allowed on this repository.` (or the equivalent for merge commits / rebase) | The merge method your queue is configured to use is disabled in the repository's GitHub settings. | Enable that merge method under **Settings → General** in GitHub, or change the queue's [merge method](/merge-queue/administration/advanced-settings#merge-method). |
+| `Resource not accessible by integration` | A branch protection rule or ruleset is blocking the Trunk GitHub app — often a wildcard rule like `*/*` that covers `trunk-merge/*` branches, or a restriction on who can merge. | Exclude `trunk-temp/*` and `trunk-merge/*` from protection rules and make sure the Trunk app is allowed to merge. See [Configure branch protection](/merge-queue/getting-started/configure-branch-protection). |
+
+Some of these fixes require repository admin access (merge settings, branch protection rules) — if you don't have it, share this page and the error with a repo admin.
+
+If the error you received isn't listed here and the cause isn't clear, contact [help@trunk.io](mailto:help@trunk.io) with the full failure message.
diff --git a/merge-queue/reference/index.mdx b/merge-queue/reference/index.mdx
index 39a2bf6a..9a3b6618 100644
--- a/merge-queue/reference/index.mdx
+++ b/merge-queue/reference/index.mdx
@@ -3,6 +3,7 @@ title: "Reference"
description: "Technical documentation and troubleshooting resources."
og:title: "Trunk Merge Queue reference"
---
+
Quick-lookup documentation for command-line tools, APIs, and troubleshooting. This section provides technical details for developers and administrators who need to automate workflows, debug issues, or find answers to common questions.
## Command-line and API
@@ -20,3 +21,6 @@ Common questions about merge queue behavior and features.
[**Troubleshooting**](./troubleshooting)\
Diagnose and resolve common issues with queue setup and operation.
+
+[**GitHub API failures**](./github-api-failures)\
+What to do when a PR fails to merge because of GitHub server errors, rate limits, or rejected merge calls.
diff --git a/merge-queue/reference/troubleshooting.mdx b/merge-queue/reference/troubleshooting.mdx
index 12749456..5c0cfc7c 100644
--- a/merge-queue/reference/troubleshooting.mdx
+++ b/merge-queue/reference/troubleshooting.mdx
@@ -7,43 +7,47 @@ og:title: "Troubleshooting Trunk Merge Queue"
## If your test PR doesn't merge automatically
-Visit [Trunk Support](../../setup-and-administration/support) for additional assistance or to contact the support team.
+ Visit [Trunk Support](../../setup-and-administration/support) for additional
+ assistance or to contact the support team.
Start here if a PR you submitted isn't merging:
-* **Check the status comments for the PR in** the [Trunk Dashboard](https://app.trunk.io/) to see what it's waiting for
-* **Stuck in "Queued"**: Usually means branch protection rules haven't passed (missing required status checks or code review) or there are merge conflicts. If the status looks correct but the PR still won't enter the queue, try [removing](/merge-queue/using-the-queue/handle-failed-pull-requests#manually-restarting-failed-pull-requests) and re-adding by commenting `/trunk merge` again on the PR.
-* **Fails when attempting to merge**: Check that squash merges are enabled for your repository in GitHub settings (`Settings > General > Allow squash merging`). Trunk Merge Queue requires squash merges to be enabled.
-* **"Permission denied" errors**: Review the [Branch Protection](/merge-queue/getting-started/configure-branch-protection#configure-branch-protection-rules) guide to make sure `trunk-temp/*` and `trunk-merge/*` branches aren't protected by wildcard rules like `*/*`.
-* **Status checks not running**: Verify your CI is configured to run on draft PRs (or `trunk-merge/**` branches if using push-triggered mode). See the [Branch Protection](/merge-queue/getting-started/configure-branch-protection#configure-branch-protection-rules) guide for details.
+- **Check the status comments for the PR in** the [Trunk Dashboard](https://app.trunk.io/) to see what it's waiting for
+- **Stuck in "Queued"**: Usually means branch protection rules haven't passed (missing required status checks or code review) or there are merge conflicts. If the status looks correct but the PR still won't enter the queue, try [removing](/merge-queue/using-the-queue/handle-failed-pull-requests#manually-restarting-failed-pull-requests) and re-adding by commenting `/trunk merge` again on the PR.
+- **Fails when attempting to merge**: Check that the [merge method](/merge-queue/administration/advanced-settings#merge-method) your queue is configured to use (squash by default) is enabled for your repository in GitHub settings (`Settings > General`).
+- **"Permission denied" errors**: Review the [Branch Protection](/merge-queue/getting-started/configure-branch-protection#configure-branch-protection-rules) guide to make sure `trunk-temp/*` and `trunk-merge/*` branches aren't protected by wildcard rules like `*/*`.
+- **Status checks not running**: Verify your CI is configured to run on draft PRs (or `trunk-merge/**` branches if using push-triggered mode). See the [Branch Protection](/merge-queue/getting-started/configure-branch-protection#configure-branch-protection-rules) guide for details.
## Common errors and stuck states
-
-**Cause:** Branch protection rules are applying to Trunk's temporary branches.
+
+ **Cause:** Branch protection rules are applying to Trunk's temporary branches.
-**Solution:** Follow the "Exclude Trunk's Temporary Branches" section above to make sure `trunk-temp/*` and `trunk-merge/*` are not protected.
-
+ **Solution:** Follow the "Exclude Trunk's Temporary Branches" section above to make sure `trunk-temp/*` and `trunk-merge/*` are not protected.
-
-**Cause:** Required status checks are not completing or not configured correctly.
+
-**Solution:**
+
+ **Cause:** Required status checks are not completing or not configured correctly.
-* Click on the pull request in the Trunk Dashboard to see which checks it's waiting for
-* Verify those checks are running in your CI provider
-* If using Push-triggered mode, make sure the check names in `trunk.yaml` exactly match your CI job names
-
+ **Solution:**
-
-**If using Draft PR mode:** Verify your CI workflows are triggered by pull requests (including draft pull requests).
+ - Click on the pull request in the Trunk Dashboard to see which checks it's waiting for
+ - Verify those checks are running in your CI provider
+ - If using Push-triggered mode, make sure the check names in `trunk.yaml` exactly match your CI job names
-**If using Push-triggered mode:**
+
-* Verify your CI workflows trigger on pushes to `trunk-merge/**` branches
-* Check that the workflows actually ran in your CI provider's interface
-* Make sure the `trunk-io` bot has permission to push to create these branches
-
+
+ **If using Draft PR mode:** Verify your CI workflows are triggered by pull requests (including draft pull requests).
+
+ **If using Push-triggered mode:**
+
+ - Verify your CI workflows trigger on pushes to `trunk-merge/**` branches
+ - Check that the workflows actually ran in your CI provider's interface
+ - Make sure the `trunk-io` bot has permission to push to create these branches
+
+
diff --git a/scripts/sync-changelog.py b/scripts/sync-changelog.py
index c735dbfa..33c749c6 100755
--- a/scripts/sync-changelog.py
+++ b/scripts/sync-changelog.py
@@ -53,8 +53,18 @@
}
MONTHS = [
- "January", "February", "March", "April", "May", "June",
- "July", "August", "September", "October", "November", "December",
+ "January",
+ "February",
+ "March",
+ "April",
+ "May",
+ "June",
+ "July",
+ "August",
+ "September",
+ "October",
+ "November",
+ "December",
]
@@ -98,14 +108,16 @@ def load_entries() -> list[dict]:
dt = date.fromisoformat(fm["date"])
except ValueError:
raise SystemExit(f"FATAL: {mdx} has unparseable date: {fm['date']!r}")
- entries.append({
- "slug": mdx.stem,
- "title": fm["title"],
- "description": fm["description"],
- "date": dt,
- "category": fm["category"],
- "path": f"changelog/{mdx.stem}",
- })
+ entries.append(
+ {
+ "slug": mdx.stem,
+ "title": fm["title"],
+ "description": fm["description"],
+ "date": dt,
+ "category": fm["category"],
+ "path": f"changelog/{mdx.stem}",
+ }
+ )
# Newest first. Stable order within a day: filename (slug) alphabetical.
entries.sort(key=lambda e: (-e["date"].toordinal(), e["slug"]))
return entries
@@ -185,7 +197,9 @@ def render_docs_json(entries: list[dict]) -> str:
Round-trips through json with indent=2 and a trailing newline."""
doc = json.loads(DOCS_JSON.read_text(encoding="utf-8"))
tabs = doc.get("navigation", {}).get("tabs", [])
- changelog_tab = next((t for t in tabs if isinstance(t, dict) and t.get("tab") == "Changelog"), None)
+ changelog_tab = next(
+ (t for t in tabs if isinstance(t, dict) and t.get("tab") == "Changelog"), None
+ )
if changelog_tab is None:
raise SystemExit("FATAL: docs.json has no Changelog tab")
@@ -202,24 +216,40 @@ def render_docs_json(entries: list[dict]) -> str:
for year in sorted(by_year.keys(), reverse=True):
month_groups: list = []
for month in sorted(by_year[year].keys(), reverse=True):
- month_groups.append({
- "group": MONTHS[month - 1],
- "pages": [e["path"] for e in by_year[year][month]],
- })
- new_pages.append({
- "group": str(year),
- "pages": month_groups,
- })
+ month_groups.append(
+ {
+ "group": MONTHS[month - 1],
+ "pages": [e["path"] for e in by_year[year][month]],
+ }
+ )
+ new_pages.append(
+ {
+ "group": str(year),
+ "pages": month_groups,
+ }
+ )
changelog_tab["pages"] = new_pages
return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
-def maybe_write(path: Path, new_text: str, check_only: bool) -> bool:
- """Compare desired content against current. Return True if a change is/would-be made."""
+def maybe_write(
+ path: Path, new_text: str, check_only: bool, *, semantic_json: bool = False
+) -> bool:
+ """Compare desired content against current. Return True if a change is/would-be made.
+
+ With semantic_json=True, compare parsed JSON instead of raw text: prettier owns
+ docs.json's formatting (e.g. it collapses short arrays onto one line), so a
+ byte-for-byte comparison against json.dumps output would report perpetual drift."""
current = path.read_text(encoding="utf-8") if path.exists() else ""
if current == new_text:
return False
+ if semantic_json and current:
+ try:
+ if json.loads(current) == json.loads(new_text):
+ return False
+ except json.JSONDecodeError:
+ pass
if check_only:
print(f"DRIFT: {path.relative_to(REPO_ROOT)}")
return True
@@ -236,7 +266,9 @@ def main() -> int:
drift = False
# 1. docs.json
- drift |= maybe_write(DOCS_JSON, render_docs_json(entries), check_only)
+ drift |= maybe_write(
+ DOCS_JSON, render_docs_json(entries), check_only, semantic_json=True
+ )
# 2. changelog/index.mdx (all entries)
fm = extract_existing_frontmatter(MASTER_INDEX)
@@ -258,7 +290,9 @@ def main() -> int:
print(f" {cat}: {counts[cat]}{in_product}")
if check_only and drift:
- print("\nERROR: changelog nav is out of sync. Run `python3 scripts/sync-changelog.py`.")
+ print(
+ "\nERROR: changelog nav is out of sync. Run `python3 scripts/sync-changelog.py`."
+ )
return 1
return 0