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

65 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Как контрибьютить
## Ветка и 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](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).