kk0t9
7bbef6886f
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Alexander <akotenev2003@gmail.com>
64 lines
4.5 KiB
Markdown
64 lines
4.5 KiB
Markdown
# Контрибьютинг в «Штурман»
|
|
|
|
Спасибо за интерес! «Штурман» — open-source русскоязычный companion-слой («ОС поверх Linux») для авто на
|
|
**RK3588**: быстрый Slint-UI + голосовой RU-ассистент, читающий OBD/CAN **только на чтение**, + расширяемый
|
|
Plugin API. Лицензия **MIT**. Общение и комментарии — по-русски; код-идентификаторы — как есть.
|
|
|
|
## 1. Красные линии (нерушимы)
|
|
|
|
Это не обсуждается и проверяется в каждом ревью:
|
|
|
|
1. **Никогда не safety-critical** — никаких интеграций с управляющими ЭБУ (двигатель/тормоза/ABS/ESP/руль/
|
|
подушки); в системе нет actuator-путей.
|
|
2. **CAN только на чтение** — допустимы стандартные OBD-II **read**-запросы (Mode 01/03/07/09/0A); запрещены
|
|
write/actuator/Mode-04/UDS-write — их не существует в коде, на D-Bus и в SDK.
|
|
|
|
PR, добавляющий такой путь, **отклоняется**. Граница и энфорсмент — [`docs/contracts/safety.md`](docs/contracts/safety.md).
|
|
|
|
## 2. Источник правды — `docs/`
|
|
|
|
Дизайн (Tier 0–3 + контракты + roadmap) — в [`docs/`](docs/). Не противоречь докам; если реальность
|
|
расходится с доком — **синхронизируй док** (двунаправленный шов), а не «молча обойди». Точка входа —
|
|
[`CLAUDE.md`](CLAUDE.md).
|
|
|
|
## 3. Рабочий цикл (фаза реализации)
|
|
|
|
- **Roadmap ведёт** ([`docs/roadmap.md`](docs/roadmap.md)). Цикл на веху: **спека → TDD → реализация →
|
|
verify в Lima-VM → коммит**. **Код не пишем до утверждённой спеки.** Спеки — в [`docs/specs/`](docs/specs/).
|
|
- Тестируемость без машины (принцип #13): каждая фича поставляется со своим симулятором/моком.
|
|
|
|
## 4. Стиль кода и тесты
|
|
|
|
- Rust везде в проде (Python — только dev/симуляторы). Формат и линт: `cargo fmt` + `cargo clippy -D warnings`
|
|
(через `just lint`).
|
|
- Пирамида тестов: unit → integration → E2E. `just test` зелёный до PR.
|
|
|
|
## 5. Лицензионная гигиена (#12)
|
|
|
|
- Зависимости — **MIT/Apache-2.0/BSD/ISC**-совместимые. Заражающий дистрибуцию копилефт (**GPL/AGPL**) —
|
|
избегаем или изолируем отдельным процессом. **LGPL — гранулярно** (динамическая/системная линковка
|
|
допустима, не blanket-запрет).
|
|
- **`cargo deny check` обязателен** (CI-гейт). Любые исключения (напр. `slint` под GPL-3.0 — см.
|
|
[`docs/specs/`](docs/specs/)) — **явные и задокументированные** в `deny.toml`.
|
|
|
|
## 6. Коммиты, ветки, DCO
|
|
|
|
- Сообщения: `feat/fix/chore/docs(<area>): …`. Ветка — от `main` (в `main` не коммитим без явного «ок»).
|
|
- **DCO sign-off обязателен:** каждый коммит — с `git commit -s` (Developer Certificate of Origin,
|
|
файл [`DCO`](DCO)). CLA нет.
|
|
- В конце сообщения коммита (для AI-ассистированных правок): `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
|
|
|
|
## 7. PR-чеклист
|
|
|
|
- [ ] `just ci` зелёный (lint + test + deny).
|
|
- [ ] Не нарушает красные линии (§1).
|
|
- [ ] Доки синхронизированы (§2), если поведение/контракт изменились.
|
|
- [ ] Добавлены тесты (unit/integration/E2E по уровню изменения).
|
|
- [ ] Коммиты подписаны (`-s`).
|
|
|
|
## 8. Поведение и обсуждение
|
|
|
|
Уважительно и по делу (Code of Conduct — будет добавлен `CODE_OF_CONDUCT.md`, ориентир — Contributor
|
|
Covenant). Вопросы и предложения — в GitHub Issues/Discussions; крупные 🟡-развилки — в «Риск-реестре»
|
|
[`docs/roadmap.md`](docs/roadmap.md).
|