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

6.4 KiB
Raw Permalink Blame History

Правила репозитория 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 допускается на русском.
/// 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.