Bidra til Kshana

Takk for interessen. Kshana har som mål å være en nøytral, reproduserbar, ærlig validert referanse for hybrid kvante-/klassisk PNT. Bidrag holdes til den terskelen: korrekthet, kildehenvisninger og reproduserbarhet foran bredde.

Hvordan prosjektet styres — hvem som bestemmer, den tekniske terskelen og grensen mellom åpent og lukket — er dokumentert i GOVERNANCE.md.

Utvikling#

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

De valgfrie språkbindingene er funksjonsstyrte og av som standard (så byggingen over og kontrollen av avhengigheter berører dem aldri). For å jobbe med 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 raske sløyfen#

Disse tar sekunder. De er en delmengde av jobben check i ci.yml, i samme rekkefølge, så en feil her er en feil der:

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

• Reproduserbarhet er en fast invariant. En endring som gjør (scenario, seed, version) ikke-deterministisk, er en feil. Tilfeldighet må gå gjennom den seedede tilfeldighetsgeneratoren; kvante- og klassiske kjøringer bruker uavhengige, deterministisk utledede seeder.
• Hygiene i repoet. Commits og innhold må ikke ha etterslep eller bunntekster som tilskriver automatiserte verktøy, og må ikke navngi en AI-assistent som forfatter noe sted i innhold, filnavn eller historikk. Vakten håndhever dette.

Før du pusher — den fulle porten#

scripts/gate.sh er den kanoniske porten: den kjører cargo test --all uavkortet, deretter scripts/check-repeatability.sh for å kjøre bibliotekssuiten noen ganger til, fordi et kappløp i trådinterleaving er usynlig i én enkelt kjøring. Først ved suksess skriver den .gate-receipt.json (ikke sporet — maskintilstand om én kjøring, ikke innhold).

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 treg med vilje — 62-79 minutter i sunn jevn drift, ifølge toppteksten i scripts/gate.sh, som har det gjeldende tallet — og det er ingen tidsavbrudd, fordi et tidsavbrudd kort nok til å være nyttig ville drept en sunn kjøring. En delmengdekjøring som kom tilbake grønn, er ikke en port: begge feilene denne mekanismen finnes for, slapp gjennom på den måten.

Bidragsytere som jobber fra en fork trenger ikke kvitteringskroken — den er en lokal vedlikeholderport, og CI er det som faktisk styrer en pull request. Å kjøre gate.sh før du åpner en, betyr bare at CI ikke forteller deg noe du ikke allerede visste.

Legge til eller endre en sensormodell#

1. Hver numeriske parameter trenger proveniens. Legg kildehenvisningen i modellens provenance-streng og i scenariofilen. Ingen anonyme konstanter.
2. Valider mot standardrelasjonen, ikke bare intern konsistens — for eksempel Allan-deviasjon for klokker, Groves' feilvekst for dead-reckoning i treghetsnavigasjon, omregningen fra tid til avstand for tidsoverføring. Legg til en test som viser at simulert utdata gjengir den publiserte verdien eller relasjonsverdien innenfor en oppgitt toleranse.
3. Vær ærlig om modenhet. Statusregisteret er src/verification.rs::verification_matrix() — legg til eller endre raden der, navngi den eksterne referansen (eller si rett ut at det ikke finnes noen, noe som gjør den til Modelled), og generer deretter de publiserte artefaktene på nytt med cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md og web/data/verification-matrix.json er alle generert fra den funksjonen og sier «ikke rediger for hånd» av en grunn. Oppdater fortellingen i docs/VALIDATION.md også når prosaen trenger det, og merk tall som er mål eller resultater fra bakkedemonstratorer som det.

Tester#

• Testdrevet: skriv den feilende testen først, med den forventede verdien utledet for hånd fra fysikken/relasjonen før du implementerer.
• Deterministiske tester hevder eksakte (håndutledede) verdier; statistiske tester hevder en oppgitt toleranse og midler helst over seeder for å kontrollere spredningen.

Commits og versjonering#

• Conventional Commits (feat:, fix:, docs:, test:, chore: …).
• Semantisk versjonering. Før 1.0 kan skjemaet for scenario/resultat endres; fremhev brytende endringer.
• Utgivelser lages med en tag vX.Y.Z, og publiseringen er automatisk, men ordnet. Arbeidsflyten Auto-tag pusher taggen når CI er grønn på main ved en versjonsøkning. Arbeidsflyten Release kjører full verifisering på det taggede commitet, og først når den består, publiserer den til crates.io, Python Package Index (PyPI), npm, ghcr.io, registeret for Model Context Protocol (MCP) og JetBrains Marketplace; deretter kontrollerer den at hver kanal serverer versjonen, og bygger kshana.dev på nytt fra taggen. Ingen kjører cargo publish for hånd. Trinnene, og hvordan du prøver en mislykket publisering på nytt, står i docs/RELEASING.md.

Vedlikehold av endringsloggen (påkrevd)#

Hver endring som er synlig for brukere, oppdaterer CHANGELOG.md:

1. Legg til en oppføring under avsnittet [Unreleased], i riktig gruppe (Added / Changed / Fixed / Removed / Documented / Planned).
2. Ved utgivelse gir du [Unreleased] nytt navn til den nye [x.y.z] - YYYY-MM-DD, starter en fersk [Unreleased], øker version i Cargo.toml (så engine_version i resultat-JSON stemmer), oppdaterer sammenligningslenkene nederst og tagger vx.y.z.
3. Hold oppføringene korte og brukerrettede; lenk til saker/PR-er der det er nyttig.

En pull request som endrer oppførsel uten en oppføring i endringsloggen, er ufullstendig.

Eksportkontroll#

PNT-robusthet og kvantesensing kan berøre eksportkontroll for varer med dobbelt bruksområde. Hold det offentlige repoet til generiske, publiserte modeller og metoder. Alt som ligner eksportfølsom robusthets- eller anti-spoofing-dybde, hører hjemme i det private laget, ikke her. Er du i tvil, spør før du bidrar med det.

Lisens#

Kshana er dobbeltlisensiert (AGPL-3.0 eller en kommersiell lisens fra Ashforde OÜ — se LICENSING.md). For at det skal fortsette å fungere, må bidrag kunne brukes under begge lisensene. Ved å bidra godtar du derfor at:

1. bidraget ditt lisensieres inn under AGPL-3.0-only; og
2. du også gir Ashforde OÜ en evigvarende, verdensomspennende, royaltyfri, uigenkallelig lisens til å bruke, endre og relisensiere bidraget ditt som en del av den kommersielt lisensierte utgaven av Kshana (det vil si også distribuere det på kommersielle vilkår som ikke er AGPL). Du beholder opphavsretten til bidraget ditt.

Denne lette dobbeltlisensieringen — ikke en overdragelse av opphavsrett — er det som lar prosjektet forbli åpent og tilby en kommersiell utgave. Hvis du ikke kan gi (2) (for eksempel kode som eies av arbeidsgiver), si fra i pull requesten din før du bidrar.

Unntak: integrations/opencpn/plugin/. Den mappen er lisensiert under GPL-3.0-or-later (se LICENSE) og ligger utenfor den kommersielle lisensen. Bidrag til den lisensieres inn under GPL-3.0-or-later bare; tildeling (2) gjelder ikke for dem.

Signer hvert commit for å bekrefte Developer Certificate of Origin: git commit -s (legger til en Signed-off-by-linje).