Přispívání do Kshana

Děkujeme za váš zájem. Kshana chce být neutrální, reprodukovatelnou, poctivě ověřovanou referencí pro hybridní kvantové a klasické PNT. Příspěvky se posuzují podle této laťky: správnost, citace a reprodukovatelnost mají přednost před šíří záběru.

Jak je projekt řízen — kdo rozhoduje, technická laťka a hranice mezi otevřeným a uzavřeným — je zdokumentováno v GOVERNANCE.md.

Vývoj#

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

Volitelné jazykové vazby jsou řízeny příznaky funkcí a ve výchozím stavu vypnuté (takže výše uvedený build a brána auditu závislostí se jich nikdy nedotknou). Chcete-li na nich pracovat:

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

Před každým commitem — rychlá smyčka#

Tyto kroky trvají sekundy. Jsou podmnožinou úlohy check v ci.yml, ve stejném pořadí, takže selhání zde je selháním 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

Reprodukovatelnost je pevná invariantní podmínka. Změna, která učiní (scenario, seed, version) nedeterministickým, je chyba. Náhodnost musí procházet seedovaným generátorem náhodných čísel; kvantové a klasické běhy používají nezávislé, deterministicky odvozené seedy.
Hygiena repozitáře. Commity a obsah nesmějí nést žádné atribuční patičky ani zápatí automatizovaných nástrojů a nesmějí jako autora uvádět AI asistenta nikde v obsahu, názvech souborů ani historii. Toto vynucuje hlídač.

Před pushem — úplná brána#

scripts/gate.sh je kanonická brána: spouští cargo test --all bez zkracování a poté scripts/check-repeatability.sh, aby ještě několikrát znovu spustila sadu knihovny, protože souběh při prokládání vláken je při jediném běhu neviditelný. Teprve po úspěchu zapíše .gate-receipt.json (nesledovaný — stav stroje o jednom běhu, nikoli obsah).

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?

Je záměrně pomalá — 62–79 minut ve zdravém ustáleném stavu, podle hlavičky scripts/gate.sh, která nese aktuální údaj — a nemá žádný časový limit, protože limit dostatečně krátký, aby byl užitečný, by zdravý běh zabil. Běh podmnožiny, který skončil zeleně, není brána: obě vady, kvůli nimž tento mechanismus existuje, jím prošly.

Přispěvatelé pracující z forku háček pro potvrzenku (receipt) nepotřebují — je to lokální brána správce a pull request ve skutečnosti hlídá CI. Spuštění gate.sh před jeho otevřením jen znamená, že vám CI neřekne nic, co byste už nevěděli.

Přidání nebo změna modelu senzoru#

Každý číselný parametr potřebuje původ. Uveďte citaci v řetězci provenance modelu i v souboru scénáře. Žádné anonymní konstanty.
Ověřujte proti standardnímu vztahu, nejen proti vnitřní konzistenci — např. Allanova odchylka u hodin, Grovesův růst chyby inerciálního výpočtu polohy u inerciálních senzorů, převod čas→vzdálenost u přenosu času. Přidejte test, že simulovaný výstup reprodukuje zveřejněnou hodnotu nebo hodnotu daného vztahu v rámci uvedené tolerance.
Buďte poctiví ohledně zralosti. Registr stavů je src/verification.rs::verification_matrix() — přidejte nebo upravte tam řádek, uveďte jeho externí orákulum (nebo otevřeně napište, že žádné není, čímž se stává Modelled) a poté znovu vygenerujte publikované artefakty příkazem cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md a web/data/verification-matrix.json se všechny generují z této funkce a z dobrého důvodu uvádějí „neupravujte ručně“. Aktualizujte také vyprávění v docs/VALIDATION.md, když to text vyžaduje, a označte hodnoty, které jsou cíle nebo výsledky pozemního demonstrátoru, jako takové.

Testy#

Nejprve test: napište nejprve selhávající test s očekávanou hodnotou odvozenou ručně z fyziky nebo vztahu, ještě před implementací.
Deterministické testy tvrdí přesné (ručně odvozené) hodnoty; statistické testy tvrdí uvedenou toleranci a ideálně průměrují přes seedy, aby se omezil rozptyl.

Commity a verzování#

Conventional Commits (feat:, fix:, docs:, test:, chore: …).
Sémantické verzování. Před verzí 1.0 se schéma scénářů a výsledků může měnit; upozorněte na zásadní změny.
Vydání se vytvářejí značkou vX.Y.Z a publikování je automatické, ale uspořádané. Pracovní postup Auto-tag odešle značku, jakmile je CI na main zelené při zvýšení verze. Pracovní postup Release spustí úplné ověření na označeném commitu a teprve když projde, publikuje do crates.io, Python Package Index (PyPI), npm, ghcr.io, registru Model Context Protocol (MCP) a JetBrains Marketplace; poté zkontroluje, že každý kanál servíruje danou verzi, a znovu sestaví kshana.dev ze značky. Nikdo nespouští cargo publish ručně. Postup a způsob opakování neúspěšného publikování jsou v docs/RELEASING.md.

Údržba changelogu (povinná)#

Každá změna viditelná uživateli aktualizuje CHANGELOG.md:

Přidejte záznam do oddílu [Unreleased], ve správné skupině (Added / Changed / Fixed / Removed / Documented / Planned).
Při vydání přejmenujte [Unreleased] na novou [x.y.z] - YYYY-MM-DD, začněte novou [Unreleased], zvyšte version v Cargo.toml (aby engine_version ve výsledném JSON odpovídalo), aktualizujte odkazy na porovnání dole a označte značkou vx.y.z.
Záznamy pište stručně a z pohledu uživatele; kde je to užitečné, odkazujte na issues/PR.

Pull request, který mění chování bez záznamu v changelogu, je neúplný.

Exportní kontrola#

Odolnost PNT a kvantové snímání se mohou dotýkat kontrol vývozu zboží dvojího užití. Veřejný repozitář držte u obecných, zveřejněných modelů a metod. Cokoli, co se podobá hloubce odolnosti a ochrany proti spoofingu citlivé z hlediska vývozu, patří do soukromé nadstavby, ne sem. Pokud si nejste jisti, zeptejte se dříve, než to přispějete.

Licence#

Kshana je licencována duálně (AGPL-3.0 nebo komerční licence od Ashforde OÜ — viz LICENSING.md). Aby to nadále fungovalo, musí být příspěvky použitelné pod oběma licencemi. Přispíváním tedy souhlasíte s tím, že:

váš příspěvek je licencován příchozí licencí AGPL-3.0-only; a
také udělujete Ashforde OÜ trvalou, celosvětovou, bezúplatnou, neodvolatelnou licenci k užití, úpravě a podlicencování vašeho příspěvku jako součásti komerčně licencované edice Kshana (tj. k šíření i za jinými než AGPL komerčními podmínkami). Autorská práva k příspěvku si ponecháváte.

Toto lehké duální licenční udělení — nikoli převod autorských práv — umožňuje, aby projekt zůstal otevřený a zároveň nabízel komerční edici. Pokud nemůžete udělit (2) (například u kódu vlastněného zaměstnavatelem), uveďte to ve svém pull requestu před přispěním.

Výjimka: integrations/opencpn/plugin/. Tento adresář je licencován GPL-3.0-or-later (viz jeho LICENSE) a je mimo komerční licenci. Příspěvky do něj jsou licencovány příchozí licencí GPL-3.0-or-later pouze; udělení (2) se na ně nevztahuje.

Každý commit podepište, abyste potvrdili Developer Certificate of Origin: git commit -s (přidá řádek Signed-off-by).