Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
95 lines (64 loc) · 5.91 KB

CONTRIBUTING.md

File metadata and controls

95 lines (64 loc) · 5.91 KB
Raw

Как участвовать в разработке TrackStudio

Спасибо за интерес к проекту. Здесь описано, как собрать TrackStudio, что учитывать при изменениях и как оформить pull request.

Если вы ИИ-агент или используете ассистента для работы с кодом — более подробные правила по архитектуре и стилю лежат в AGENTS.md и docs/architecture.md.

Быстрый старт

Требуется Docker и Docker Compose. Всё остальное поднимается само.

git clone https://github.com/maximkr/TrackStudio.git
cd TrackStudio
docker compose up -d --build

Приложение — http://localhost:8080, вход root / root.

docker compose logs -f trackstudio   # логи приложения
docker compose logs -f migrator      # логи миграций Liquibase
docker compose down                  # остановить
docker compose down -v               # остановить и удалить базу (данные пропадут)

Сборка без Docker

Нужен JDK 21. Gradle подтягивается wrapper-ом.

./gradlew build          # компиляция + тесты
./gradlew war            # собрать TrackStudio.war
./gradlew printVersion   # версия сборки

Версия определяется плагином com.palantir.git-version по git-тегам. Если собираете из shallow clone без тегов, вместо версии получится хеш коммита — при клонировании используйте полную историю.

Прежде чем браться за задачу

  • Загляните в открытые issue. Если задача уже описана — напишите в ней, что берётесь.
  • Для крупных изменений сначала откройте issue с обсуждением. Так вы не потратите время на подход, который не подойдёт по архитектурным причинам.
  • Изменения из списка ниже требуют предварительного обсуждения в любом случае.

Требуют архитектурного ревью

Из docs/architecture.md, раздел 14:

  • изменение порядка захвата блокировок;
  • изменения модели ACL;
  • изменения структуры кешей и их инвалидации;
  • процесс старта приложения и конфигурация;
  • изменение контракта REST API.

При таких изменениях обновите docs/architecture.md и AGENTS.md в том же PR.

Стиль кода

Подробности — в AGENTS.md. Коротко:

  • классы PascalCase, методы camelCase, константы UPPER_SNAKE_CASE, пакеты в нижнем регистре;
  • таблицы БД — с префиксом gr_;
  • логирование через SLF4J API: org.slf4j.Logger и LoggerFactory. Новый код на commons-logging не пишем;
  • порядок импортов: java, затем javax, затем org.apache, затем com.trackstudio;
  • кодировка исходников и ресурсов — UTF-8;
  • в kernel-коде — только Lock API (LockManager, ReadWriteLock), не смешивать блокировки и synchronized в одном методе;
  • наружу отдавать копии или неизменяемые представления, внутренние коллекции не публиковать.

Изменения схемы базы

Только через Liquibase, каталог liquibase/. Правки схемы без миграции не принимаются. Учитывайте, что changelog разделён по языкам — changelog-master-en.xml и changelog-master-ru.xml.

Тесты

Проект использует JUnit 4, тесты лежат в src/test/java/.

./gradlew test
./gradlew test --tests "com.trackstudio.kernel.manager.IndexManagerTest"

Честное предупреждение: сейчас все существующие тест-классы помечены @Ignore, то есть фактически выполняется ноль тестов. Новый код с тестами приветствуется особенно — это то место, где проект больше всего нуждается в помощи.

Pull request

  1. Ответвитесь от main, ветку называйте осмысленно: fix/..., feature/..., docs/....
  2. Убедитесь, что ./gradlew build проходит локально.
  3. Опишите в PR, что меняется и зачем. Для изменений в UI приложите скриншоты до и после.
  4. Дождитесь зелёного CI — на каждый PR запускаются сборка с тестами, сборка Docker-образа и анализ CodeQL.
  5. Один PR — одно логическое изменение. Не смешивайте рефакторинг с исправлением бага.

Коммиты пишите так, чтобы из заголовка было понятно, что сделано. Строгий формат не навязывается.

Лицензия

Отправляя pull request, вы соглашаетесь, что ваш вклад распространяется на условиях Apache License 2.0.