b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
65 lines
4.1 KiB
Markdown
65 lines
4.1 KiB
Markdown
# Как контрибьютить
|
||
|
||
## Ветка и 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).
|