О проекте

Проектная документация этой книги: как она собрана, как её собирать и проверять и где находится источник истины. Саму книгу смотрите в оглавлении.

Карта проекта

Книга: публикуется в четырёх локалях в locales/; см. spec/locales.md. Эта локаль, en-gb-oxendict/topics/ (63 файла), en-gb-oxendict/front-matter/ и приложения в части 9 это рукописный источник; en-001, en-gb и en-us выводятся из него.
Источник истины: spec/ в корне репозитория (не публикуется на сайте). Структура объявлена в spec/structure.md, правила письма в spec/conventions.md, а орфография в spec/oxford-spelling.md. Всё остальное строится так, чтобы соответствовать.
Инструменты: tools/localize.py выводит остальные три локали; tools/gen_nav.py генерирует навигацию; tests/validate.py проверяет соблюдение спецификации; justfile связывает их.
Руководство для участников: AGENTS.md в корне репозитория и руководства в разделе об участии.

Сборка и проверка

Набор проверок работает на Python 3 без других зависимостей и без доступа к сети. Задачи запускаются через just.

just test    # validate structure, style, links, and spec-vs-disk
just nav     # regenerate the generated navigation files
just check   # nav, then test
just stats   # topic and word counts

Этот репозиторий хранит содержание и спецификацию книги. В веб-сайт её превращает отдельный репозиторий software-engineering-metrics.github.io.

Как здесь работает разработка, управляемая спецификацией

Спецификация идёт первой. spec/structure.md объявляет, какие темы существуют и как они нумеруются. spec/conventions.md объявляет, как нужно писать темы. Темы пишутся так, чтобы удовлетворять обоим. tools/gen_nav.py выводит навигацию из тем, а tests/validate.py проверяет результат на соответствие спецификации. Если тема и спецификация когда-нибудь разойдутся, тест упадёт, и это сигнал выровнять их снова.

Так дрейф остаётся снаружи: изменение «закончено» только тогда, когда спецификация, темы, сгенерированная навигация и тесты все согласны.

Проектные решения, которые стоит знать

Плоские темы с десятичной нумерацией. Файлы называются locales/<locale>/topics/PP-CC-slug.md, слаг один и тот же во всех локалях. Части это целые числа; темы это десятичные дроби; N.0 это введение части. Так идентификаторы остаются стабильными, а инструменты могут сортировать и группировать без дерева каталогов.
Одна рукописная локаль, три производных. en-gb-oxendict это оксфордская орфография, фирменный стиль большинства международных органов по стандартизации (см. spec/oxford-spelling.md); en-001, en-gb и en-us механически выводятся из неё, поэтому переводы никогда не расходятся с источником.
Сгенерированная навигация. Оглавление, страницы содержания и указатель тем генерируются, поэтому они никогда не расходятся с темами.
Офлайн-тесты без зависимостей. Набор использует только стандартную библиотеку, поэтому работает где угодно, включая CI и pre-commit-хуки.
Перекрёстные ссылки остаются простым текстом. Проза ссылается на темы по десятичному номеру («см. тему 2.1»), как требует спецификация; сайт, который рендерит, отвечает за превращение этих ссылок в гиперссылки.
Без длинных тире, по правилу и по тесту. Сознательный стилистический выбор, который проверяется, чтобы оставаться верным по мере роста книги.
Каждое семейство метрик называет собственный путь манипулирования. Это единственное правило шаблона, не имеющее аналога в родственном проекте software-engineering-guide: оно существует потому, что вся тема этой книги измерение, а значит, риск самого измерения должен быть первоклассным, а не подразумеваемым.

Что почитать дальше