ICE-NET/RULES.md
loki5512344 2e61688eb3
Some checks failed
rust-ci / checks (push) Has been cancelled
Initial import: ICE-NET research docs and Rust workspace (v0.4)
- 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)
2026-11-13 12:28:48 +01:00

71 lines
6.4 KiB
Markdown
Raw Permalink 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.

# Правила репозитория 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`**.