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

オープン
#45 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
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時間
マージ済み PR(30日)
7

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。