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

未关闭
#45 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
48/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
markdown, python
领域
documentation

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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

主要语言
Python
星标
2
派生
5
平均合并
2 天 11 小时
30 天内合并 PR
7

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。