Files
java-word-pdf/docs/development/contributing.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

4.1 KiB
Raw Blame History

Как контрибьютить

Ветка и PR

Репозиторий: git.pjandro.ru:pjandro/java-word-pdf. Защищённые ветки — main, master, dev: прямо в них не коммитим.

  1. Ветка от свежей main (git switch -c <name>).
  2. Коммиты логическими блоками.
  3. Перед push — полный гейт: ./mise.sh run verify.
  4. git push -u origin <name> → 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):

  • 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.