Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

🎯 [Подэпик] Документы разошлись с кодом, с собой и с англоязычной витриной

Aperta
  • Qualcosa non va?
#989 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à
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
markdown, python
Ambito
documentation, tooling

Direzione di ricerca

Start with docs/audit/2026-08-10-full-roles.md § 5-бис and the four remaining actions in the issue; then read check_docs_guardrails.py, README.en.md, README.md, and CLAUDE.md § Источники истины. The scope spans documentation, code-link checks, and issue templates, so confirm which part you are taking on before starting. Done means the listed acceptance criteria hold, including matching security-section coverage in both READMEs.

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

Descrizione

area/docs audit difficulty/easy documentation

Фаза 3 аудита 2026-08-10 (документы как система) + ось «код → документы» из фазы 4. Документ: docs/audit/2026-08-10-full-roles.md § 5-бис

124 находки, ни одной high — расхождение в документе не портит вердикт грейдера. Но часть из них вводит в заблуждение о рисках, и это отдельный разговор.

Находки

Галочка ставится тем же заходом, что и мерж закрывающего PR, и называет исход. Неотмеченная строка означает «не закрыта или не проверена»; где состояние подтверждено по файлам прямо сейчас — это сказано в строке.

Безопасность описана неверно — единственная группа, где ошибка документа меняет решение пользователя о рисках:

  • READER-4-01 — заявлено «ничего не уходит в сеть», хотя каналов исходящего трафика четыре → раздел «Куда грейдер ходит в сеть»: таблица каналов с указанием, что и когда уходит (#1193)
  • READER-4-04 — не назван главный локальный риск: проверяемое решение исполняется с доступом к secrets.json с OAuth-токеном (SECURITY.md:41)
  • READER-4-02 — история указывалась «в рабочей папке», хотя лежит в ~/.stepik-grader/history.db; после #1186 туда же уехали настройки → таблица данных называет, где лежит каждый файл (#1193)
  • PAIR-4-02 — лимит памяти заявлен «на POSIX (Linux/macOS)», а prlimit — только Linux: на macOS лимита нет (configuration.md:378)
  • CANON-2-04 — безусловное «изоляции ФС и сети нет» стоит в том же файле, где описан --sandbox (configuration.md:381)
  • CANON-2-03 — канон по безопасности не был определён: CLAUDE.md не упоминал SECURITY.md → строка в таблице источников истины (#1193)

Английская витрина обрывается:

  • READER-5-01 / PAIR-4-01 — секции безопасности нет вовсе (README.en.md:139). Жива: в оглавлении файла нет ни одного раздела про безопасность
  • PAIR-4-03 — у --sandbox обещана «FS isolation» без оговорок из таблицы SECURITY.md (README.en.md:160)
  • READER-5-02 / READER-5-03 — ссылки на веб-интерфейс и «Full reference» молча уводят в русскоязычные docs/ (README.en.md:112,192)
  • READER-5-05 — дан только шим stepik-grader, без запасного python -m stepik_grader (README.en.md:66)

Ссылки из кода никуда не ведут — ось, которую не проверяет ни один guard (check_docs_guardrails.py смотрит только внутри *.md, LINK-1-04):

  • LINK-1-01 — docs/audit-2026-07.md в history.py:5 и ещё трёх местах: файл переехал в docs/archive/
  • LINK-1-02 — docs/trace-format.md без направления dev/ (trace-player.js:207): ни файла, ни якоря
  • LINK-1-05 — сообщения об ошибках слали в docs/, которых нет при установке через pip и pipx → в тексты подставлен абсолютный URL, гейт локалей заворачивает репо-относительные пути (#1129)
  • LINK-1-04 — сам guard не смотрит ссылки из кода: докстринги, комментарии, строки локалей

Канон разошёлся с копиями:

  • CANON-5-01 — объявлено отменённое правило web→core: код ходит в core напрямую, минуя фасад (web-contracts.md:258)
  • CANON-5-02 — статус-трекер числит палитру команд реализованной, хотя она удалена (web-design.md:149)
  • CANON-5-03 — CSP назван строгим и запрещающим инлайн-стили, хотя style-src разрешает 'unsafe-inline' (web-interface.md:416)
  • PAIR-3-02 — ADR требует «тихо деградировать», а тот же ADR и код (#794) — называть повреждение вслух (adr/0011-local-persistence.md:86)
  • READER-3-01 — точкой входа назван несуществующий cli.py. Не воспроизводится: в CLAUDE.md больше нет ни одного упоминания cli.py, точки входа описаны через пакет cli/
  • CANON-4-05 — ratchet на внешнюю витрину ловит только домен artvsmark.github.io, docs_url не ограничен ничем (test_glossary.py:199)

Онрамп контрибьютора рвётся:

  • READER-2-01 — pytest на подмножестве падал из-за глобального fail_under=85: красное на первом же цикле правки → порог переехал в флаг шага CI (#1122)
  • READER-2-02 — список «локальных гейтов, зеркалящих CI» неполон: 4 команды против 6 guard-скриптов (CONTRIBUTING.md:35)
  • READER-2-03 — требование «язык артефактов — русский» есть только в CLAUDE.md, который контрибьютор читать не обязан (CONTRIBUTING.md:330)
  • LINK-3-03 — ни один шаблон issue не ставит area/* и difficulty/*, хотя политика объявляет их обязательными

Что делать

  1. Начать с SECURITY.md — сделано (#1193). Осталась вторая половина группы: README.en.md, где раздела о безопасности нет вовсе.
  2. Расширить check_docs_guardrails.py на ссылки из кода (докстринги, комментарии, строки локалей) — иначе класс вернётся.
  3. Пройти список канона в CLAUDE.md § Источники истины и привести копии в соответствие либо заменить их ссылками.
  4. Шаблоны issue — с обязательными метками.

Критерий приёмки

Ни одной ссылки из кода в несуществующий документ (проверяется guard'ом). README.en.md и README.md совпадают по составу разделов о безопасности. Ни один документ не описывает удалённую функцию как живую.

Generated by Claude Code

Lingua principale
Python
Stelle
3
Fork
6
Merge medio
2h 41m
PR unite (30g)
48

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.

Altre issue di ArtVsMark/Stepik-Python-Grader

Tutte le issue di ArtVsMark/Stepik-Python-Grader

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.