fix(doc): handle ignored errors without span (e.g. missing optional roots) by caugner · Pull Request #455 · mdn/rari

caugner · 2025-12-19T16:15:21Z

Description

Suppress errors for missing optional roots:

BLOG_ROOT
CONTRIBUTOR_SPOTLIGHT_ROOT
CURRICULUM_ROOT
GENERIC_CONTENT_ROOT

Motivation

Prevent these from showing up in content PRs like this one.

Additional details

Related issues and pull requests

Affects: - BLOG_ROOT - CONTRIBUTOR_SPOTLIGHT_ROOT - CURRICULUM_ROOT - GENERIC_CONTENT_ROOT

github-actions · 2025-12-19T16:19:08Z

67f285c was deployed to: https://rari-pr455.review.mdn.allizom.net/

crates/rari-doc/src/cached_readers.rs

caugner · 2026-01-15T17:31:53Z

@LeoMcA I have now:

Extracted a capture_doc_error() helper function that emits a warning, and sets the ignore = true flag for optional missing root errors.
Fixed the issue recording logic.

I verified this by commenting out generic_content_root in my .config.toml, then running:

cargo run build -f ../content/files/en-us/web/http/guides/browser_detection_using_the_user_agent/index.md --issues ./issues.json

I compared the result between main and this branch, and the "unknown" issue is no longer in the issues.json in this branch:

% jd issues-*.json
@ [""]
- [{"col":0,"end_col":0,"end_line":0,"fields":[["message","No generic content config found"]],"file":"","ic":0,"ignore":true,"line":0,"req":0,"spans":[]}]

LeoMcA · 2026-01-19T09:16:33Z

crates/rari-doc/src/issues.rs

+
        if !issue.ignore {
+            // Record first.
            event.record(&mut issue);
+        }
+
+        if !issue.ignore {
+            // Check again after recording.


Actually I was wrong in my comment wasn't I: this should already be only recording issues with ignore = false: so I'm not sure what this change does, unless event.record mutates issue.ignore? If so we should leave a comment explaining that, and see if wrapping event.record in the if statement is necessary.

At first, this was a bit confusing for me as well, but here's what I think is happening:

The on_event() handler creates a new Issue where ignore is set to false:

rari/crates/rari-doc/src/issues.rs

Lines 167 to 175 in d51f68b

let mut issue = Issue {

req: 0,

ic: -1,

col: 0,

line: 0,

end_col: 0,

end_line: 0,

file: String::default(),

ignore: false,

Then ignore is set to true only if we have a span with IssueEntries that has entry.ignore = true:

rari/crates/rari-doc/src/issues.rs

Lines 205 to 207 in d51f68b

if entries.ignore {

issue.ignore = entries.ignore;

}

However, warn!(ignore = true, "{e}") only creates an event, not a span, so it isn't covered by this.

The event.record() call causes the Visit implementation for Issue (not IssueEntries) to be called, which sets ignore to true if the Issue has a field named ignore:

rari/crates/rari-doc/src/issues.rs

Lines 112 to 132 in d51f68b

impl Visit for Issue {

fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {

self.fields.push((field.name(), format!("{value:?}")));

}

fn record_str(&mut self, field: &Field, value: &str) {

if field.name() == "file" {

self.file = value.to_string();

} else {

self.fields.push((field.name(), value.to_string()));

}

}

fn record_u64(&mut self, field: &Field, value: u64) {

if field.name() == "req" {

self.req = value;

}

}

fn record_bool(&mut self, field: &Field, value: bool) {

if field.name() == "ignore" {

self.ignore = value;

}

}

I verified this behavior now by adding eprintln!() statements where ignore is set (869f673):

% cargo run --quiet build -f ../content/files/en-us/web/http/guides/browser_detection_using_the_user_agent/index.md --issues ./issues.json 1 ↵ ✭ Building everything 🛠️ Took: 8.858ms for reading 1 docs Setting Issue.ignore = true (issue: Issue { req: 0, ic: 0, col: 0, line: 0, end_col: 0, end_line: 0, file: "", ignore: true, fields: [("message", "No generic content config found")], spans: [] }) Took: 336.059ms to build spas (111) Took: 783.511ms to build content docs (1) Took: 36.093ms to build search index

I will update the comments to better explain this.

@LeoMcA I have now:

Extracted fn populate_issue_from_scope() to make it clearer that the logic only applies to issues in a span scope. (e451c5a)

Refined the comments, moving one between the blocks. (c217f6d)

This reverts commit 869f673.

Makes it clear that this only applies to Events with a span.

LeoMcA

Nice, looks good!

chore(doc): suppress errors about missing optional roots

dde2d1e

Affects: - BLOG_ROOT - CONTRIBUTOR_SPOTLIGHT_ROOT - CURRICULUM_ROOT - GENERIC_CONTENT_ROOT

caugner requested a review from a team as a code owner December 19, 2025 16:15

caugner requested a review from LeoMcA December 19, 2025 16:15

caugner temporarily deployed to review December 19, 2025 16:18 — with GitHub Actions Inactive

LeoMcA requested changes Jan 15, 2026

View reviewed changes

crates/rari-doc/src/cached_readers.rs Outdated Show resolved Hide resolved

caugner marked this pull request as draft January 15, 2026 15:29

caugner changed the title ~~chore(doc): suppress errors about missing optional roots~~ chore(doc): ignore errors about missing optional roots Jan 15, 2026

caugner temporarily deployed to review January 15, 2026 16:53 — with GitHub Actions Inactive

caugner force-pushed the suppress-optional-root-errors branch from 18346ed to 7c0af70 Compare January 15, 2026 16:54

chore(doc): extract capture_doc_error()

a6b343d

caugner force-pushed the suppress-optional-root-errors branch from 7c0af70 to a6b343d Compare January 15, 2026 16:57

caugner temporarily deployed to review January 15, 2026 17:01 — with GitHub Actions Inactive

Merge branch 'main' into suppress-optional-root-errors

893112a

caugner temporarily deployed to review January 15, 2026 17:19 — with GitHub Actions Inactive

fix(doc): filter ignored issues correctly

d51f68b

caugner temporarily deployed to review January 15, 2026 17:29 — with GitHub Actions Inactive

caugner requested a review from LeoMcA January 15, 2026 17:32

caugner marked this pull request as ready for review January 15, 2026 17:32

LeoMcA approved these changes Jan 19, 2026

View reviewed changes

caugner added 2 commits January 19, 2026 11:02

test(doc): debug issue ignoring

869f673

Revert "test(doc): debug issue ignoring"

366a15a

This reverts commit 869f673.

caugner temporarily deployed to review January 19, 2026 10:05 — with GitHub Actions Inactive

caugner added 2 commits January 19, 2026 11:15

refactor(doc): extract populate_issue_from_scope()

e451c5a

Makes it clear that this only applies to Events with a span.

chore(doc): refine issue ignore comments

c217f6d

caugner requested a review from LeoMcA January 19, 2026 10:23

caugner deployed to review January 19, 2026 10:23 — with GitHub Actions View deployment

caugner changed the title ~~chore(doc): ignore errors about missing optional roots~~ fix(doc): handle ignored error events without span (e.g. missing optional roots) Jan 19, 2026

caugner changed the title ~~fix(doc): handle ignored error events without span (e.g. missing optional roots)~~ fix(doc): handle ignored errors without span (e.g. missing optional roots) Jan 19, 2026

LeoMcA approved these changes Jan 19, 2026

View reviewed changes

LeoMcA merged commit 3684232 into main Jan 19, 2026
18 checks passed

LeoMcA deleted the suppress-optional-root-errors branch January 19, 2026 10:29

mdn-bot mentioned this pull request Jan 19, 2026

chore(main): release 0.2.10 #465

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(doc): handle ignored errors without span (e.g. missing optional roots)#455

fix(doc): handle ignored errors without span (e.g. missing optional roots)#455
LeoMcA merged 8 commits intomainfrom
suppress-optional-root-errors

caugner commented Dec 19, 2025

Uh oh!

github-actions bot commented Dec 19, 2025 •

edited

Loading

Uh oh!

Uh oh!

caugner commented Jan 15, 2026 •

edited

Loading

Uh oh!

LeoMcA Jan 19, 2026

Uh oh!

caugner Jan 19, 2026

Uh oh!

caugner Jan 19, 2026

Uh oh!

LeoMcA left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	let mut issue = Issue {
	req: 0,
	ic: -1,
	col: 0,
	line: 0,
	end_col: 0,
	end_line: 0,
	file: String::default(),
	ignore: false,

	impl Visit for Issue {
	fn record_debug(&mut self, field: &Field, value: &dyn fmt::Debug) {
	self.fields.push((field.name(), format!("{value:?}")));
	}
	fn record_str(&mut self, field: &Field, value: &str) {
	if field.name() == "file" {
	self.file = value.to_string();
	} else {
	self.fields.push((field.name(), value.to_string()));
	}
	}
	fn record_u64(&mut self, field: &Field, value: u64) {
	if field.name() == "req" {
	self.req = value;
	}
	}
	fn record_bool(&mut self, field: &Field, value: bool) {
	if field.name() == "ignore" {
	self.ignore = value;
	}
	}

Conversation

caugner commented Dec 19, 2025

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

caugner commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LeoMcA Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

caugner Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

caugner Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

LeoMcA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Dec 19, 2025 •

edited

Loading

caugner commented Jan 15, 2026 •

edited

Loading