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 摘要。