No guide has a review date yet, so "Last reviewed" never shows

Aperta
#45 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
markdown, python
Ambito
documentation

Direzione di ricerca

Start with docs/AGENTS.md, CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, and the review-date handling in scripts/prepare-mkdocs.py, scripts/catalog.py, and overrides/main.html. Review each guide under docs/ against its sources before adding a marker; then run python scripts/prepare-mkdocs.py and zensical build --strict -f mkdocs.gen.yml. Done means reviewed guides show dates on the published pages, the rule is consistent, and a check catches broken URL-to-source mapping.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation help wanted severity: medium

Summary

The review-date feature from #40 works, but no guide has a <!-- reviewed: YYYY-MM-DD --> marker yet. No page shows "Last reviewed", and every build prints 21 warnings, one per guide.

Where

  • docs/channels/*.md, docs/resources/*.md, docs/ad-templates/TEMPLATES.md (no marker in any guide)
  • scripts/prepare-mkdocs.py:73 (prints the warnings)
  • scripts/catalog.py:261 (review_status, "has no valid review date")
  • docs/AGENTS.md:32 and CONTRIBUTING.md:19 (the rule, stated two different ways)
  • .github/PULL_REQUEST_TEMPLATE.md:16 (new-page checklist)
  • overrides/main.html:14 (renders the date)

Details

git grep "reviewed:" -- docs finds only the rule in docs/AGENTS.md. Running python scripts/prepare-mkdocs.py prints:

Warning: channels/SEA.md has no valid review date
Warning: channels/SOCIAL.md has no valid review date
... (21 lines, one per guide)

So mkdocs.gen.yml gets no extra.reviewed_dates, and the template never shows a date.

Two smaller gaps in the same area:

  • docs/AGENTS.md:32 says only a date older than 12 months warns. CONTRIBUTING.md:19 and the code also warn on missing, invalid, and future dates.
  • The PR template's new-page checklist does not mention the marker.

Impact

Readers still cannot tell when a guide was last checked, which was the goal of #40. Because 21 warnings print on every build, contributors learn to ignore them, including the one that matters: a stale date.

Suggested fix

  1. Review each guide against its sources, then add <!-- reviewed: YYYY-MM-DD --> on its own line after the H1. Only date a guide that was actually reviewed. The accuracy passes merged on 2026-11-15 and 2026-11-16 (commits d407010, 8ed956c, d46aec8) may already count for the guides they covered.
  2. Make docs/AGENTS.md:32 match CONTRIBUTING.md:19: missing, invalid, future, and stale dates all warn.
  3. Add the marker to the new-page item in .github/PULL_REQUEST_TEMPLATE.md.
  4. Add a test for the template's URL-to-source mapping in overrides/main.html:16 (channels/SEA/ becomes channels/SEA.md). Today only the generated extra map is tested, so a change in page URLs would hide every date without failing a check. One option: after zensical build in CI, check that site/channels/SEA/index.html contains "Last reviewed".

Acceptance criteria

  • Every reviewed guide has a marker, and python scripts/prepare-mkdocs.py warns only for guides that still need a review.
  • "Last reviewed" appears on those guides on the published site.
  • docs/AGENTS.md, CONTRIBUTING.md, and the PR template describe the rule the same way.
  • A test fails if the template stops finding a page's review date.

Getting started

  • Relevant files: the guides under docs/, docs/AGENTS.md, CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, overrides/main.html
  • Run the checks: python scripts/prepare-mkdocs.py, then zensical build --strict -f mkdocs.gen.yml (see CONTRIBUTING.md for the full list)
  • Related: #40

Filed by repo-audit/full-audit at 2aa0316. Severity: medium. Effort: M. audit-key: documentation|docs/channels|reviewed-date-markers

Lingua principale
Python
Stelle
2
Fork
5
Merge medio
2g 11h
PR unite (30g)
7

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.