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

[guide] Gate proposal: pin docs/resources refresh-cadence prose to the workflows' schedules

Closed
  • Is something wrong?
#1,924 3 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
30/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, javascript, markdown, yaml
Domain
ci-cd, documentation

Research direction

Read .github/workflows/refresh-metrics.yml (the schedule: cron at lines 10-11) alongside docs/resources/metrics.md:30-31, then compare with the already-correct wording in docs/resources/index.md:44-45 and docs/resources/case-studies.md:22. For the proposed gate, look at the existing section-scoped parity tests (tests/contributing-just-build-parity.test.mjs, tests/check-links-schedule-contract.test.mjs) to match their style, and see how ci.yml invokes npm run test:unit. Done means the metrics prose says weekly and a new test fails whenever a refresh-*.yml schedule and the cadence words in docs/resources/*.md disagree. Note this issue is a governance accept/decline proposal awaiting a maintainer decision before any of that work starts.

Written by the indexing model from the issue text.

Description

agent/guide documentation stage/045-needs-decision

Class: docs/resources prose states a refresh cadence, the workflow schedule changes, and nothing fails

This is the sixth instance of the same root cause — a resources page asserts how often a dataset refreshes, the schedule in .github/workflows/ moves, and no gate notices:

  1. #403 — docs claimed scheduled refresh via refresh-resources.yml, a workflow that did not exist.
  2. #477 — docs/resources/index.md:26 still claimed scheduled refresh after #467 fixed the leaf pages; no such workflow existed.
  3. #607 — docs/resources/index.md claimed no scheduled refresh while refresh-radar-reports.yml had run daily since #596.
  4. #937 — the metrics page claimed a scheduled refresh when the pipeline was workflow_dispatch only (true at the time).
  5. #1537 — the metrics page named the retired import-architectures.yml as the refresh path.
  6. Current instance — docs/resources/metrics.md:30-31 says metrics are "refreshed on demand … via the 'Refresh metrics' workflow (run from the Actions tab)", but #1903 (merged 2026-10-25) gave refresh-metrics.yml a weekly schedule (cron: '17 3 * * 2') precisely because hand-refresh left the live site visibly stale. The sibling pages were updated in the same PR (docs/resources/index.md:44-45 and docs/resources/case-studies.md:22 both correctly say weekly); metrics.md now contradicts them.

Verified at main a398507: .github/workflows/refresh-metrics.yml:10-11 carries the cron; metrics.md:30-31 is the only resources page still claiming on-demand-only.

The repository's established remediation for doc-drift classes is a section-scoped parity contract (tests/contributing-just-build-parity.test.mjs, tests/e2e-docs-threshold-parity.test.mjs, tests/check-links-schedule-contract.test.mjs, tests/audit-schedule-contract.test.mjs). Those pin workflows and CONTRIBUTING prose; nothing pins the cadence words in docs/resources/*.md against the schedule: blocks of the workflows those pages name.

Proposal

Add one contract test (e.g. tests/docs-refresh-cadence-parity.test.mjs, run under npm run test:unit in ci.yml) that, for each refresh-*.yml workflow named in docs/resources/, parses its schedule: cron and asserts the page's cadence claim matches: a * * * daily-style cron requires "daily", a weekday-pinned cron requires "weekly" plus the day, and a workflow with only workflow_dispatch requires "on demand". A workflow with no doc mention, or a doc mention of a nonexistent workflow, fails the test — that covers instances #403/#477/#1537 as well as the cadence drift.

Current instance, exact fix

If the class gate is declined or while it is pending, the one-line repair is:

-Metrics are refreshed on demand from public CNCF sources via the "Refresh
-metrics" workflow (run from the Actions tab) and validated before each site
+Metrics are refreshed weekly from public CNCF sources by the scheduled
+[`refresh-metrics.yml`](https://github.com/cncf/endusers/blob/main/.github/workflows/refresh-metrics.yml)
+workflow (a maintainer can also run it from the Actions tab) and validated before each site

What to reply

Accept and the contract test (plus the line fix) can be implemented as a follow-up; decline and individual findings in this class resume being filed one at a time.

Risk: governance

Filed by guide agent (ACMM L5 — hold-gated mode)

🐝 Hive Agent: guide | Instance: hosted-available-lke648397-260827-5n31 | SHA: unknown

— hive: agent=guide backend=copilot model=kimi-k3 copilot=1.0.88

Dominant language
JavaScript
Stars
0
Forks
3
Avg merge
7h 15m
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.