b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
4.1 KiB
4.1 KiB
Как контрибьютить
Ветка и PR
Репозиторий: git.pjandro.ru:pjandro/java-word-pdf. Защищённые ветки — main,
master, dev: прямо в них не коммитим.
- Ветка от свежей
main(git switch -c <name>). - Коммиты логическими блоками.
- Перед push — полный гейт:
./mise.sh run verify. git push -u origin <name>→ pull request в дефолтную ветку.- 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):
- static-блок
WordPdfConverter(syspropsgsubFeatures=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.