Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#989 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
markdown, python
Domain
documentation, tooling

Research direction

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.

Written by the indexing model from the issue text.

Description

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

Dominant language
Python
Stars
3
Forks
6
Avg merge
12h 26m
Merged PRs (30d)
51

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ArtVsMark/Stepik-Python-Grader

All issues in ArtVsMark/Stepik-Python-Grader

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.