Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[quality] Content-only CI path skips the document-contract suites that guard authored documents

Open
  • Is something wrong?
#2,002 4 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@mrbobbytables is already working on this.

Since Oct 30, 2026.

  • #2010 by @mrbobbytables — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
25/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
github-actions, javascript
Domain
ci-cd, testing

Research direction

Read .github/workflows/ci.yml, especially the “Check content contracts” step, and inspect the listed suites alongside the eligible authored document paths described in the issue. The issue reports that the fix is a single workflow test list and gives the proposed additions; completion means those suites run on the content-only path. An open linked pull request (#2010) already covers the issue.

Written by the indexing model from the issue text.

Description

agent/quality stage/010-actionable testing

Finding

ADR 0011 keeps "the applicable document-contract checks" on the focused path.
The implementation keeps three: tests/docs-contract.test.mjs,
tests/markdown-references.test.mjs and
tests/community-group-coverage.test.mjs
(.github/workflows/ci.yml, step "Check content contracts"). Other
document-contract suites read the same eligible authored documents and are
skipped, so a prose-only PR can pass every focused check and still break the
required Validate repository job. merge_group classifies the merge commit
the same way, so the PR merges green and the next full-validation PR — anyone
else's — opens red.

Two instances verified at c686990 on a clean npm ci tree:

  1. Unindexed ADR. Adding adr/0012-example-decision.md alone:
    classifyChanges('pull_request', <sha>, [{status:'A', path:'adr/0012-example-decision.md'}])
    returns {"documentOnly":true,...}; the trio passes (pass 19 / fail 0) and
    runDocumentLint passes prettier, cspell and markdownlint; but
    node --test tests/adr-contract.test.mjs fails
    "every number-prefixed ADR file is listed in the index". adr/ is not part
    of the Docusaurus build, so the production build does not catch it either.
  2. Broken relative link in a root document. Appending
    [missing page](docs/nope-not-here.md) to README.md:
    tests/markdown-references.test.mjs reports fail 0,
    tests/root-docs-links.test.mjs reports fail 1. A broken link in
    README.md is also visible to anyone reading the repository on GitHub.

This is one gate-configuration defect, not two findings: both are the same
missing entries in one list.

Recommendation

Extend the node --test list in the "Check content contracts" step with the
document-contract suites whose inputs are classifier-eligible documents
(adr/**, blog/**, docs/** except the data-backed and architecture-generated
pages, and the ROOT_DOCUMENTS set). Suites that only read ineligible inputs
(tests/events-page.test.mjs — docs/events/index.md is data-backed;
tests/mdx-active-content.test.mjs — docs/architectures/_security-regression.md
is not eligible) are deliberately left out.

Replace, in .github/workflows/ci.yml:

      - name: Check content contracts
        if: ${{ !cancelled() && env.CONTENT_ONLY == 'true' }}
        run: >-
          node --test tests/docs-contract.test.mjs
          tests/markdown-references.test.mjs
          tests/community-group-coverage.test.mjs

with:

      - name: Check content contracts
        if: ${{ !cancelled() && env.CONTENT_ONLY == 'true' }}
        run: >-
          node --test tests/docs-contract.test.mjs
          tests/markdown-references.test.mjs
          tests/community-group-coverage.test.mjs
          tests/adr-contract.test.mjs
          tests/architecture-submission-contract.test.mjs
          tests/architectures-sidebar-contract.test.mjs
          tests/blog-frontmatter.test.mjs
          tests/content-security-contract.test.mjs
          tests/contributing-e2e-setup.test.mjs
          tests/contributing-just-build-parity.test.mjs
          tests/docs-threshold-parity.test.mjs
          tests/e2e-docs-threshold-parity.test.mjs
          tests/enduser-directory-copy.test.mjs
          tests/governance-hygiene-parity.test.mjs
          tests/root-docs-links.test.mjs
          tests/skills-manifest.test.mjs

The full list runs 134 tests, fail 0, in 1.2s locally at c686990, so the
focused path stays fast. tests/content-only-ci-workflow.test.mjs asserts the
step's if: expression and not its command, so no test file needs to change
with it; this does not touch any threshold (ADR 0008).

This change needs a human or an ISSUES_PRS_MERGE agent to land. The fix is
confined to .github/workflows/ci.yml, and this lane's token is minted without
the Workflows permission, so no PR it pushes could contain the edit. Nothing
here lives outside .github/workflows/, so there is no partial PR to open.

Priority

  • Impact: high — a prose-only merge turns a required check red for every other
    contributor until someone bisects it.
  • Effort: low — one list in one workflow step.

Filed by quality agent (hold-gated mode)

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: c686990

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88

Dominant language
JavaScript
Stars
0
Forks
3
Avg merge
7h 8m
Merged PRs (30d)
565

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cncf/endusers

All issues in cncf/endusers

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.