Bidrag til Kshana

Tak for din interesse. Kshana sigter mod at være en neutral, reproducerbar, ærligt valideret reference for hybrid kvante-/klassisk PNT. Bidrag holdes op mod den tærskel: korrekthed, henvisninger og reproducerbarhed frem for bredde.

Hvordan projektet styres, altså hvem der beslutter, den tekniske tærskel og grænsen mellem åbent og lukket, er beskrevet i GOVERNANCE.md.

Udvikling#

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

De valgfrie sprogbindinger er feature-gated og slået fra som standard (så buildet ovenfor og afhængighedsrevisionsgaten aldrig berører dem). Sådan arbejder du på dem:

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

Før hver commit: den hurtige løkke#

Disse tager sekunder. De er en delmængde af jobbet check i ci.yml, i samme rækkefølge, så en fejl her er en fejl dér:

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

• Reproducerbarhed er en hård invariant. En ændring, der gør (scenario, seed, version) ikke-deterministisk, er en fejl. Tilfældighed skal gå gennem den seedede RNG; kvante- og klassiske kørsler bruger uafhængige, deterministisk udledte seeds.
• Repository-hygiejne. Commits og indhold må ikke bære attributionsafsnit eller sidefødder fra automatiserede værktøjer og må ikke nævne en AI-assistent som forfatter nogen steder i indhold, filnavne eller historik. Vagten håndhæver det.

Før du pusher: den fulde gate#

scripts/gate.sh er den kanoniske gate: den kører cargo test --all uforkortet og derefter scripts/check-repeatability.sh for at køre biblioteks-suiten et par gange mere, fordi et kapløb mellem tråde er usynligt ved en enkelt kørsel. Først ved succes skriver den .gate-receipt.json (ikke sporet: maskintilstand om én kørsel, ikke indhold).

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?

Den er langsom med vilje: 62-79 minutter i sund stabil tilstand, ifølge headeren i scripts/gate.sh, som bærer det aktuelle tal, og der er ingen timeout, fordi en timeout, der var kort nok til at være nyttig, ville dræbe en sund kørsel. En delmængdekørsel, der kom tilbage grøn, er ikke en gate: begge de fejl, denne mekanisme findes for, nåede igennem på den måde.

Bidragydere, der arbejder fra en fork, behøver ikke kvitteringskrogen: det er en lokal vedligeholdergate, og CI er det, der faktisk gater en pull request. At køre gate.sh, før du åbner en, betyder blot, at CI ikke fortæller dig noget, du ikke allerede vidste.

Tilføjelse eller ændring af en sensormodel#

1. Hver numerisk parameter har brug for proveniens. Skriv henvisningen i modellens provenance-streng og i scenariefilen. Ingen anonyme konstanter.
2. Valider mod standardrelationen, ikke kun intern konsistens: for eksempel Allan-deviation for ure, Groves' fejlvækst ved dødregning for inertial, omregningen fra tidssynkronisering til afstandsmåling for tidsoverførsel. Tilføj en test af, at det simulerede output gengiver den offentliggjorte værdi eller relationsværdien inden for en angivet tolerance.
3. Vær ærlig om modenhed. Statusregistret er src/verification.rs::verification_matrix(): tilføj eller ret rækken dér, nævn dens eksterne uafhængige reference (eller sig tydeligt, at der ingen er, hvilket gør den til Modelled), og generér derefter de offentliggjorte artefakter igen med cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md og web/data/verification-matrix.json er alle genereret af den funktion og siger »må ikke redigeres i hånden« af en grund. Opdatér også fortællingen i docs/VALIDATION.md, når prosaen har brug for det, og mærk tal, der er mål eller resultater fra jorddemonstratorer, som sådanne.

Tests#

• Testdrevet: skriv først den fejlende test, med den forventede værdi udledt i hånden af fysikken eller relationen, før du implementerer.
• Deterministiske tests kontrollerer eksakte (håndudledte) værdier; statistiske tests kontrollerer en angivet tolerance og midler helst over seeds for at holde spredningen i skak.

Commits og versionering#

• Conventional Commits (feat:, fix:, docs:, test:, chore: …).
• Semantic Versioning. Før 1.0 kan scenarie- og resultatskemaet ændre sig; fremhæv ændringer, der bryder kompatibilitet.
• Udgivelser udløses af et vX.Y.Z-tag, og publiceringen er automatisk, men ordnet. Auto-tag-workflowet pusher tagget, når CI er grøn på main ved et versionsspring. Release-workflowet kører den fulde verifikation på det taggede commit, og først når den består, publicerer det til crates.io, Python Package Index (PyPI), npm, ghcr.io, Model Context Protocol (MCP)-registret og JetBrains Marketplace; derefter kontrollerer det, at hver kanal serverer versionen, og genopbygger kshana.dev fra tagget. Ingen kører cargo publish i hånden. Trinene og hvordan en mislykket publicering forsøges igen står i docs/RELEASING.md.

Vedligeholdelse af changelog (påkrævet)#

Hver ændring, brugeren kan se, opdaterer CHANGELOG.md:

1. Tilføj en post under afsnittet [Unreleased], i den rigtige gruppe (Added / Changed / Fixed / Removed / Documented / Planned).
2. Ved udgivelse omdøbes [Unreleased] til den nye [x.y.z] - YYYY-MM-DD, der startes en ny [Unreleased], hæves version i Cargo.toml (så engine_version i resultat-JSON svarer til), opdateres sammenligningslinkene nederst, og vx.y.z tagges.
3. Hold poster korte og brugerrettede; link til issues/PR'er, hvor det er nyttigt.

En pull request, der ændrer adfærd uden en post i changelog, er ufuldstændig.

Eksportkontrol#

PNT-robusthed og kvantesensorer kan berøre eksportkontrol af produkter med dobbelt anvendelse. Hold det offentlige repository til generiske, offentliggjorte modeller og metoder. Alt, der ligner eksportfølsom dybde i robusthed eller anti-spoofing, hører hjemme i det private overlay, ikke her. Er du i tvivl, så spørg, før du bidrager med det.

Licens#

Kshana har dobbelt licens (AGPL-3.0 eller en kommerciel licens fra Ashforde OÜ, se LICENSING.md). For at det kan blive ved med at fungere, skal bidrag kunne bruges under begge licenser. Ved at bidrage accepterer du derfor, at:

1. dit bidrag licenseres indgående under AGPL-3.0-only; og
2. du også giver Ashforde OÜ en evig, verdensomspændende, royaltyfri, uigenkaldelig licens til at bruge, ændre og relicensere dit bidrag som en del af Kshanas kommercielt licenserede udgave (dvs. også at distribuere det på kommercielle vilkår, der ikke er AGPL). Du beholder ophavsretten til dit bidrag.

Denne lette dobbeltlicenstildeling, som ikke er en overdragelse af ophavsret, er det, der lader projektet være åbent og tilbyde en kommerciel udgave. Hvis du ikke kan give (2) (for eksempel kode, der ejes af en arbejdsgiver), så sig det i din pull request, før du bidrager.

Undtagelse: integrations/opencpn/plugin/. Den mappe er licenseret under GPL-3.0-or-later (se dens LICENSE) og ligger udenfor den kommercielle licens. Bidrag til den licenseres indgående kun under GPL-3.0-or-later only; tildeling (2) gælder ikke for dem.

Underskriv hvert commit for at bekræfte Developer Certificate of Origin: git commit -s (tilføjer en linje Signed-off-by).