Współtworzenie Kshana

Dziękujemy za zainteresowanie. Kshana ma być neutralnym, odtwarzalnym, rzetelnie sprawdzonym względem niezależnych wzorców punktem odniesienia dla hybrydowego kwantowo-klasycznego PNT. Wkład jest oceniany według tego progu: poprawność, cytowania i odtwarzalność przed zakresem.

Sposób zarządzania projektem — kto decyduje, jaki jest próg techniczny i gdzie przebiega granica między otwartym a zamkniętym — opisano w GOVERNANCE.md.

Rozwój#

cargo build
cargo test          # all tests must pass
cargo clippy        # keep it warning-clean
cargo fmt

Opcjonalne wiązania językowe są włączane cechami i domyślnie wyłączone (więc powyższa kompilacja i bramka audytu zależności nigdy ich nie dotykają). Aby nad nimi pracować:

maturin develop --features python                 # Python extension (needs maturin)
wasm-pack build --target web -- --features wasm    # WebAssembly module
cargo clippy --features python --features wasm     # lint the binding modules

Przed każdym zatwierdzeniem — szybka pętla#

Trwa to kilka sekund. To podzbiór zadania check z ci.yml, w tej samej kolejności, więc porażka tutaj jest porażką tam:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
./scripts/check-reproducible.sh     # reference scenario is byte-identical across runs
./scripts/check-no-attribution.sh   # repo hygiene (see below)
./scripts/check-version-sync.sh     # every version surface agrees with Cargo.toml
./scripts/check-doc-coverage.sh     # missing-docs ratchet: the count may fall, never rise

Odtwarzalność jest twardą niezmienniczą regułą. Zmiana, która sprawia, że (scenario, seed, version) jest niedeterministyczne, jest błędem. Losowość musi przepływać przez generator z ziarnem (seed); przebiegi kwantowe i klasyczne używają niezależnych, deterministycznie wyprowadzonych ziaren.
Higiena repozytorium. Zatwierdzenia i treść nie mogą zawierać stopek ani dopisków z automatyczną atrybucją narzędzia i nie mogą wskazywać asystenta AI jako autora nigdzie w treści, nazwach plików ani historii. Wymusza to strażnik.

Przed wypchnięciem — pełna bramka#

scripts/gate.sh to kanoniczna bramka: uruchamia cargo test --all w całości, a następnie scripts/check-repeatability.sh, aby kilka razy ponownie uruchomić zestaw biblioteki, ponieważ wyścig przeplotu wątków jest niewidoczny w pojedynczym przebiegu. Tylko po sukcesie zapisuje .gate-receipt.json (nieśledzony — stan maszyny dotyczący jednego przebiegu, a nie treść).

scripts/gate.sh
REPEAT=0 scripts/gate.sh           # canonical suite only, no repeatability loop — a LOCAL
                                   # shortcut: the pre-push gate refuses its receipt unless
                                   # KSHANA_MIN_REPEAT_RUNS=0 is also set on the push
TEST_THREADS=6 scripts/gate.sh     # cap per-binary concurrency if the run is memory-starved
scripts/check-gate-receipt.sh      # is there a valid receipt for the commit being pushed?
scripts/install-gate-hook.sh --check   # is the pre-push hook installed on this clone?

Jest celowo wolna — 62-79 minut w zdrowym stanie ustalonym, według nagłówka scripts/gate.sh, który zawiera bieżącą wartość — i nie ma limitu czasu, ponieważ limit na tyle krótki, by był użyteczny, zabiłby zdrowy przebieg. Przebieg podzbioru, który wyszedł na zielono, nie jest bramką: oba defekty, dla których ten mechanizm istnieje, przeszły właśnie tą drogą.

Osoby pracujące z forka nie potrzebują haka potwierdzenia — to lokalna bramka opiekuna, a to CI faktycznie bramkuje pull request. Uruchomienie gate.sh przed otwarciem pull requesta oznacza po prostu, że CI nie powie ci niczego, czego jeszcze nie wiesz.

Dodawanie lub zmiana modelu czujnika#

Każdy parametr liczbowy wymaga pochodzenia. Umieść cytowanie w ciągu provenance modelu i w pliku scenariusza. Żadnych anonimowych stałych.
Sprawdzaj względem standardowej zależności, a nie tylko spójności wewnętrznej — np. odchylenie Allana dla zegarów, narastanie błędu nawigacji zliczeniowej według Grovesa dla czujników inercyjnych, przeliczenie czas→odległość dla transferu czasu. Dodaj test, że symulowany wynik odtwarza opublikowaną wartość lub wartość z zależności w podanej tolerancji.
Bądź rzetelny co do dojrzałości. Rejestr statusów to src/verification.rs::verification_matrix() — dodaj lub popraw tam wiersz, wskaż jego zewnętrzną wyrocznię (lub powiedz wprost, że jej nie ma, co czyni go Modelled), a następnie wygeneruj ponownie opublikowane artefakty za pomocą cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md i web/data/verification-matrix.json są generowane z tej funkcji i z powodu mówią „nie edytować ręcznie”. Zaktualizuj też narrację docs/VALIDATION.md, gdy tekst tego wymaga, i oznaczaj wartości będące celami lub wynikami demonstratora naziemnego jako takie.

Testy#

Programowanie sterowane testami: najpierw napisz test, który zawodzi, z oczekiwaną wartością wyprowadzoną ręcznie z fizyki lub zależności, zanim zaimplementujesz.
Testy deterministyczne sprawdzają dokładne (wyprowadzone ręcznie) wartości; testy statystyczne sprawdzają podaną tolerancję i najlepiej uśredniają po ziarnach, aby kontrolować rozrzut.

Zatwierdzenia i wersjonowanie#

Conventional Commits (feat:, fix:, docs:, test:, chore: …).
Semantic Versioning. Przed 1.0 schemat scenariusza i wyniku może się zmieniać; zaznaczaj zmiany niezgodne wstecz.
Wydania powstają przez tag vX.Y.Z, a publikacja jest automatyczna, ale uporządkowana. Przepływ Auto-tag wypycha tag, gdy CI jest zielone na main po podniesieniu wersji. Przepływ Release uruchamia pełną weryfikację na otagowanym zatwierdzeniu i dopiero gdy ta przejdzie, publikuje w crates.io, Python Package Index (PyPI), npm, ghcr.io, rejestrze Model Context Protocol (MCP) i JetBrains Marketplace; następnie sprawdza, czy każdy kanał serwuje tę wersję, i przebudowuje kshana.dev z tagu. Nikt nie uruchamia cargo publish ręcznie. Kroki i sposób ponowienia nieudanej publikacji są w docs/RELEASING.md.

Prowadzenie dziennika zmian (wymagane)#

Każda zmiana widoczna dla użytkownika aktualizuje CHANGELOG.md:

Dodaj wpis w sekcji [Unreleased], w odpowiedniej grupie (Added / Changed / Fixed / Removed / Documented / Planned).
Przy wydaniu zmień nazwę [Unreleased] na nowe [x.y.z] - YYYY-MM-DD, zacznij nowe [Unreleased], podnieś version w Cargo.toml (aby engine_version w JSON wyniku się zgadzało), zaktualizuj linki porównawcze na dole i otaguj vx.y.z.
Wpisy pisz zwięźle i z perspektywy użytkownika; linkuj zgłoszenia i pull requesty tam, gdzie to przydatne.

Pull request, który zmienia zachowanie bez wpisu w dzienniku zmian, jest niekompletny.

Kontrola eksportu#

Odporność PNT i sensoryka kwantowa mogą podlegać kontroli eksportu towarów podwójnego zastosowania. Publiczne repozytorium ogranicz do ogólnych, opublikowanych modeli i metod. Wszystko, co przypomina wrażliwą eksportowo głębię odporności lub ochrony przed spoofingiem, należy do prywatnej nakładki, a nie tutaj. W razie wątpliwości zapytaj przed wniesieniem wkładu.

Licencja#

Kshana ma podwójną licencję (AGPL-3.0 lub licencja komercyjna od Ashforde OÜ — zob. LICENSING.md). Aby to nadal działało, wkład musi nadawać się do użycia na obu licencjach. Dlatego, wnosząc wkład, zgadzasz się, że:

twój wkład jest licencjonowany przychodząco na podstawie AGPL-3.0-only; oraz
udzielasz również Ashforde OÜ bezterminowej, ogólnoświatowej, bezpłatnej, nieodwołalnej licencji na używanie, modyfikowanie i ponowne licencjonowanie twojego wkładu jako części komercyjnie licencjonowanego wydania Kshana (tj. także na dystrybucję na niebędących AGPL warunkach komercyjnych). Zachowujesz prawa autorskie do swojego wkładu.

To lekkie podwójne udzielenie licencji — a nie przeniesienie praw autorskich — pozwala projektowi pozostać otwartym i oferować wydanie komercyjne. Jeśli nie możesz udzielić (2) (na przykład w przypadku kodu należącego do pracodawcy), napisz o tym w pull requeście przed wniesieniem wkładu.

Wyjątek: integrations/opencpn/plugin/. Ten katalog jest licencjonowany na GPL-3.0-or-later (zob. jego LICENSE) i jest poza licencją komercyjną. Wkłady do niego są licencjonowane przychodząco na GPL-3.0-or-later wyłącznie; udzielenie (2) ich nie dotyczy.

Podpisz każde zatwierdzenie, aby poświadczyć Developer Certificate of Origin: git commit -s (dodaje wiersz Signed-off-by).