Współtworzenie Speedwave
Speedwave rozwija się w modelu open-source. Niezależnie od tego, czy naprawiasz błędy, rozwijasz obsługę platform systemowych czy udoskonalasz dokumentację, zacznij od przewodnika Konfiguracja środowiska deweloperskiego i zapoznaj się z zasadami opisanymi w rozdziale Testowanie i jakość kodu.
Wszystkie operacje deweloperskie są koordynowane za pomocą pliku Makefile. Polecenie make setup-dev instaluje narzędzia i zależności, make dev uruchamia aplikację desktopową z przeładowywaniem kodu w czasie rzeczywistym (hot-reload), a make check-all przeprowadza pełny audyt jakości CI (lintery, Rust clippy, sprawdzanie typów w Angularze, testy jednostkowe, wskaźniki pokrycia kodu oraz audyt podatności w pakietach). Zaleca się unikanie bezpośredniego wywoływania cargo lub npm, aby zachować spójność flag kompilacji w całym monorepozytorium.
Podstawowe zasady inżynierskie
Dział zatytułowany „Podstawowe zasady inżynierskie”Struktura kodu opiera się na sprawdzonych wzorcach architektonicznych:
- KISS (Keep It Simple, Stupid): Speedwave stanowi lekką warstwę orkiestracji nad środowiskami Lima, nerdctl i containerd. Należy unikać tworzenia własnych mechanizmów tam, gdzie istnieją natywne narzędzia.
- YAGNI (You Aren’t Gonna Need It): Implementujemy wyłącznie funkcjonalności zdefiniowane w aktualnych planach technicznych.
- DRY (Don’t Repeat Yourself): Współdzielona logika trafia do modułu
speedwave-runtime(lubmcp-servers/shared/dla workerów MCP). Tabele modeli i stałe posiadają jedno źródło prawdy. - SOLID: Typy wykonawcze realizują pojedyncze odpowiedzialności (
ContainerRuntimeodpowiada wyłącznie za cykl życia kontenerów), co pozwala sterownikom platform (LimaRuntime,WslRuntime) implementować wspólny traitLockedRuntime. - Reguła trzech powtórzeń (Rule of Three): Unikamy przedwczesnych abstrakcji, dopóki wzorzec nie pojawi się w trzech niezależnych miejscach.
Logowanie i diagnostyka
Dział zatytułowany „Logowanie i diagnostyka”Moduły Rusta rejestrują zdarzenia wyłącznie przez fasadę crate’a log, wykluczając bezpośrednie wywołania println! i eprintln!. Każdy strumień wyjściowy jest filtrowany przez moduł oczyszczania danych wrażliwych (log_sanitizer.rs) przed zapisem na dysk, do strumienia błędów lub warstwy IPC interfejsu graficznego.
Standardy Git i kontrola jakości
Dział zatytułowany „Standardy Git i kontrola jakości”- Obowiązuje bezwzględny zakaz omijania hooków pre-commit i pre-push w systemie Git.
- Zabronione jest wymuszanie scalania z pominięciem reguł ochrony gałęzi repozytorium.
- Każdy commit ze zmianami logicznymi musi zawierać testy automatyczne dla ścieżek poprawnych, skrajnych, błędów i przejść maszyn stanów.
- Testy z błędami muszą być niezwłocznie naprawiane; wyciszanie lub pomijanie testów jest niedozwolone.