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

Abierto
#45 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
markdown, python

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Python
Estrellas
2
Forks
5
Merge medio
2 d 11 h
PR fusionados (30 d)
7

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.