Some checks failed
rust-ci / checks (push) Has been cancelled
- Rust workspace: 7 library crates, icenetd CLI, icenet-city (Slint GUI) - Sim: fix false Delivered after a route cut, derive traffic class from payload size, per-link airtime slots (link capacity, queueing) - Docs: single docs/STATUS.md for all figures, remove v0.2/egui leftovers, drop unimplemented seed claims, uncheck store-and-forward - License: LGPL-3.0-or-later (LICENSE, LICENSES/GPL-3.0.txt)
71 lines
6.4 KiB
Markdown
71 lines
6.4 KiB
Markdown
# Правила репозитория ICE-NET · обязательные
|
||
|
||
## Структура и ограничения
|
||
|
||
1. **Не более 250 физических строк на любой авторский текстовый файл**, включая MD, Rust, Slint, TOML, Python, YAML.
|
||
2. **Не более 4 авторских файлов непосредственно в одном каталоге** (подкаталоги отдельно). Сгенерированный `Cargo.lock`, `.gitignore` и системный `.DS_Store` не учитываются при подсчёте; на исходники и `.slint` это исключение не действует.
|
||
3. Если модуль вырос — делить по ответственности, **не** сжимать код в одну строку.
|
||
4. Не размещать тесты в `src/` через `#[cfg(test)]`: unit-like и integration tests — отдельные `tests/*.rs`.
|
||
5. Не создавать crate ради каждого типа; новая граница crate требует независимой ответственности и односторонних зависимостей.
|
||
6. `workspace/tools/check_layout.py` проверяет лимиты для `.rs`, `.slint`, `.md` и конфигурации. Не обходить скрипт переименованием файла.
|
||
7. Исключение: дословные тексты лицензий (`LICENSE`, `LICENSES/`) — не авторские файлы; не править и не сокращать.
|
||
|
||
## Documentation & comments (English)
|
||
|
||
- Public crates: `//! Module or crate description.`
|
||
- Public types, traits, methods: `/// Summary.` — **rustdoc** (Rust-аналог JavaDoc).
|
||
- Для нетривиальных API применять секции `# Arguments`, `# Returns`, `# Errors`, `# Panics`, `# Examples`, `# Safety` где уместно.
|
||
- Комментарии внутри исходников — **English**, поясняют *почему*, а не буквально *что* делает строка.
|
||
- Текст документации в `docs/` и issue допускается на русском.
|
||
|
||
```rust
|
||
/// Finds a route that satisfies the traffic class policy.
|
||
///
|
||
/// # Arguments
|
||
/// - `class`: The traffic class to schedule.
|
||
///
|
||
/// # Returns
|
||
/// A route, or `None` when no eligible path exists.
|
||
///
|
||
/// # Errors
|
||
/// This operation currently does not return I/O errors.
|
||
pub fn find_route(class: TrafficClass) -> Option<Route> { /* example */ None }
|
||
```
|
||
|
||
## Архитектурные принципы
|
||
|
||
- **KISS:** сначала простейшая проверяемая реализация; избегать преждевременного async/actor/DI-фреймворка.
|
||
- **DRY:** общая логика живёт в одном crate; не превращать каждый похожий `match` в абстракцию.
|
||
- **SOLID:** маленькие интерфейсы (`Transport`, `RoutePlanner`), разделение политик и механики, инверсия зависимостей на границе с железом.
|
||
- **Hexagonal architecture:** UI и сеть — адаптеры; алгоритмы **не** импортируют GUI и операционную систему.
|
||
- Детерминированность симулятора: фиксированные seed, стабильный порядок событий, симулированное время.
|
||
- Одна ответственность на модуль; публичный API минимальный; ошибки типизированные, не `panic` на входных пакетах.
|
||
|
||
## Код, качество, безопасность
|
||
|
||
- Rust Edition 2024, `resolver = "3"`; версия инструмента согласуется с версиями GUI.
|
||
- Не применять `unsafe` без ADR + ревью; `unwrap()` в обработке входных данных запрещён.
|
||
- Запретить секреты, токены, приватные ключи и реальные данные пользователей в git/фикстурах.
|
||
- Test Pyramid: проверка инвариантов → integration → сценарии города → hardware-in-the-loop.
|
||
- Криптографическая «угроза» от ICE: только **локально разрешить/отказать/ограничить/залогировать**; никаких ответных атак.
|
||
- Code review по контрактам, тестам, потреблению RAM/airtime, privacy и зависимости.
|
||
|
||
## Definition of Done для PR
|
||
|
||
- [ ] Лимиты 250/4, rustdoc на новых публичных API, тесты в `tests/`.
|
||
- [ ] `cargo fmt`, `cargo clippy`, `cargo test` без ошибок.
|
||
- [ ] Указано, какие сценарии покрыты, какие риски и какие измерения получены.
|
||
- [ ] Не заявлена совместимость/безопасность без тестов, лицензия зависимостей проверена.
|
||
|
||
## Внешние зависимости (MVP)
|
||
|
||
- Библиотечные крейты по умолчанию работают **без crates.io-зависимостей**.
|
||
- Каждая новая зависимость требует краткого обоснования: функция, лицензия, MSRV,
|
||
транситивные зависимости, поддержка, альтернатива на std.
|
||
- GUI-зависимости только в `apps/icenet-city`, никогда в `icenet-core`/`icenet-sim`.
|
||
- Для Slint выключены defaults: без Qt, Skia, WGPU, webview, tokio или serde.
|
||
- `slint-build` нужен только для компиляции `.slint` в `build.rs`.
|
||
- В версии 0.3 GUI: Slint 1.18.1, software renderer и Winit (desktop Linux).
|
||
- Поставляемые программы требуют проверки лицензий, особенно Slint.
|
||
- Лицензия собственного кода: **LGPL-3.0-or-later** (`license` в `workspace/Cargo.toml`; каждый crate наследует её). Код других проектов с несовместимой лицензией не копировать.
|
||
- После обновления GUI **перегенерировать и закоммитить новый `Cargo.lock`**.
|