# Как контрибьютить ## Ветка и PR Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`, `master`, `dev`: прямо в них не коммитим. 1. Ветка от свежей `main` (`git switch -c `). 2. Коммиты логическими блоками. 3. Перед push — полный гейт: `./mise.sh run verify`. 4. `git push -u origin ` → pull request в дефолтную ветку. 5. CI на PR: `java` (единственный `mvn clean verify` в контейнере без fontconfig + сводка покрытия комментарием) и `web` (`npm ci`, build, lint) — оба required. `macos-sim` — не required. ## Конвенции кода - Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет); в `internal/**` — package-private, `public` только вызываемым извне пакета. - Ошибки публичного API — только `ConversionException` (и подтипы); в chart — деградация вместо падения. - Javadoc на русском: «зачем» + ссылка на секцию спецификации (§17.3.2.24, [MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке грепом восстанавливаются пары тестов). - Модели — `record`; константы UPPER_SNAKE с javadoc-обоснованием числа. - PMD-подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены. - Логирование: `java.util.logging` — корневой пакет и `internal/`; SLF4J — `internal/chart` и `wordpdf-app`; остальное молчит. ## Регрессивная конвенция (фикс бага) Каждый фикс расхождения с Word оформляется полным набором: ``` нормализатор/рендерер → юнит на правило → тест во всём конвейере → javadoc-ссылка «Регрессия — Тест#имя, фикстура …» ``` Фикстуры для новых тестов не генерируются на лету и не перезаписываются: `charts-smartart.docx` и `ole-embedded.docx` сделаны руками и **не перезаписываются никогда**; все 12 `.doc` — эталоны заказчика. ## Критические инварианты (нарушение = битый вывод) Прежде чем править ядро — прогнать глазами список (полный — `AGENTS.md`, [repo-map](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)): - static-блок `WordPdfConverter` (sysprops `gsubFeatures=false`, отключение сканов PhysicalFonts) — не удалять; - `DrawingPreRenderer` обязан идти **до** `FOSettings`, иначе FOP молча теряет диаграммы; - порядок нормализаторов правил 1–11 фиксирован; - вендорный `docx2fo.xslt` — единственный XSL-стилист, дрейф-гейт `vendoredXsltTracksJarCopy`; - `slf4j-simple` обязателен в ядре; - префикс `/word/media/chart-*` — контракт с `ChartImageHandler`; - финальный `finally`-блок: temp-шрифты, кеши картинок, возврат реестра к бандлу. ## Документация сайта Разделы сайта живут в `docs/` (кроме `docs/agent/`, `docs/standards/` — они не входят в сайт). Правка/новая страница: обязательна запись в `nav` `mkdocs.yml` (иначе strict-сборка падает). Проверка: `./mise.sh run docs-build`. Публикация — [`docs-deploy`](../operations/docs-site.md).