Osallistuminen Kshana-projektiin

Kiitos kiinnostuksestasi. Kshana pyrkii olemaan neutraali, toistettava, rehellisesti validoitu viite hybridikvantti-/klassiselle PNT:lle. Kontribuutioilta vaaditaan tämä taso: oikeellisuus, lähdeviitteet ja toistettavuus ennen laajuutta.

Tapa, jolla projektia hallitaan — kuka päättää, tekninen taso sekä avoimen ja suljetun raja — on dokumentoitu tiedostossa GOVERNANCE.md.

Kehitys#

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

Valinnaiset kielisidonnat on suojattu ominaisuuslipuilla ja ovat oletuksena pois päältä (joten yllä oleva build ja riippuvuuksien auditointiportti eivät koske niihin koskaan). Niiden parissa työskentelyyn:

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

Ennen jokaista committia — nopea silmukka#

Nämä kestävät sekunteja. Ne ovat osajoukko tiedoston ci.yml työstä check, samassa järjestyksessä, joten epäonnistuminen täällä on epäonnistuminen siellä:

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

Toistettavuus on kova invariantti. Muutos, jonka vuoksi tulos ei ole deterministinen suhteessa kolmikkoon (scenario, seed, version), on virhe. Satunnaisuuden on kuljettava siemenlukuun perustuvan RNG:n kautta; kvantti- ja klassiset ajot käyttävät riippumattomia, deterministisesti johdettuja siemenlukuja.
Repositorion hygienia. Commiteissa ja sisällössä ei saa olla automaattisten työkalujen attribuutiorivejä tai -alatunnisteita, eikä tekoälyavustajaa saa nimetä tekijäksi missään sisällössä, tiedostonimissä tai historiassa. Suoja valvoo tätä.

Ennen kuin pushaat — täysi portti#

scripts/gate.sh on kanoninen portti: se ajaa cargo test --all lyhentämättömänä ja sitten scripts/check-repeatability.sh ajaakseen kirjastosuiten vielä muutaman kerran, koska säikeiden lomittumiskilpailu ei näy yksittäisessä ajossa. Vain onnistuessaan se kirjoittaa .gate-receipt.json (ei seurattu — konetila yhdestä ajosta, ei sisältöä).

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?

Se on tarkoituksella hidas — 62-79 minuuttia terveessä vakaassa tilassa, tiedoston scripts/gate.sh otsikon mukaan, joka kantaa ajantasaisen luvun — eikä aikakatkaisua ole, koska riittävän lyhyt hyödyllinen aikakatkaisu tappaisi terveen ajon. Osajoukkoajo, joka palasi vihreänä, ei ole portti: molemmat viat, joita varten tämä mekanismi on olemassa, pääsivät sen läpi juuri niin.

Forkista työskentelevien kontribuuttoreiden ei tarvitse kuittikoukkua — se on paikallinen ylläpitäjän portti, ja CI on se, mikä oikeasti portittaa pull requestin. Tiedoston gate.sh ajaminen ennen pull requestin avaamista tarkoittaa vain, ettei CI kerro mitään, mitä et jo tiennyt.

Anturimallin lisääminen tai muuttaminen#

Jokainen numeerinen parametri tarvitsee alkuperätiedon. Laita viite mallin merkkijonoon provenance ja skenaariotiedostoon. Ei anonyymejä vakioita.
Validoi standardisuhdetta vasten, ei vain sisäistä johdonmukaisuutta — esim. Allanin poikkeama kelloille, Grovesin dead-reckoning-virheenkasvu inertialle, ajoitus→etäisyys-muunnos ajansiirrolle. Lisää testi, joka toteaa simuloidun tulosteen toistavan julkaistun/suhteen arvon ilmoitetun toleranssin sisällä.
Ole rehellinen kypsyydestä. Tilarekisteri on src/verification.rs::verification_matrix() — lisää tai muuta rivi siellä, nimeä sen ulkoinen oraakkeli (tai sano selvästi, ettei sellaista ole, mikä tekee siitä tilan Modelled), ja generoi sitten julkaistut artefaktit uudelleen komennolla cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md ja web/data/verification-matrix.json generoidaan kaikki tuosta funktiosta, ja niissä lukee ”do not edit by hand” syystä. Päivitä myös kertomus docs/VALIDATION.md, kun proosa sitä tarvitsee, ja merkitse tavoitteina tai maapohjaisen demonstraattorin tuloksina olevat luvut sellaisiksi.

Testit#

Testilähtöinen: kirjoita ensin epäonnistuva testi, ja odotettu arvo johdettu käsin fysiikasta/suhteesta ennen toteutusta.
Deterministiset testit väittävät täsmällisiä (käsin johdettuja) arvoja; tilastolliset testit väittävät ilmoitetun toleranssin ja mieluiten keskiarvoistavat siemenlukujen yli hajonnan hallitsemiseksi.

Commitit ja versiointi#

Conventional Commits (feat:, fix:, docs:, test:, chore: …).
Semantic Versioning. Ennen versiota 1.0 skenaario-/tulosskeema voi muuttua; nosta rikkovat muutokset esiin.
Julkaisut leikataan tagilla vX.Y.Z, ja julkaisu on automaattinen mutta järjestetty. Auto-tag-työnkulku pushaa tagin, kun CI on vihreä haarassa main versionnoston yhteydessä. Release-työnkulku ajaa täyden varmennuksen tagatulla commitilla, ja vain kun se läpäisee, se julkaisee crates.io:hon, Python Package Indexiin (PyPI), npm:ään, ghcr.io:hon, Model Context Protocol (MCP) -rekisteriin ja JetBrains Marketplaceen; sitten se tarkistaa, että jokainen kanava tarjoaa version, ja rakentaa kshana.dev:n tagista uudelleen. Kukaan ei aja komentoa cargo publish käsin. Vaiheet ja epäonnistuneen julkaisun uudelleenyritys ovat tiedostossa docs/RELEASING.md.

Changelogin ylläpito (pakollinen)#

Jokainen käyttäjälle näkyvä muutos päivittää tiedostoa CHANGELOG.md:

Lisää merkintä osion [Unreleased] alle oikeaan ryhmään (Added / Changed / Fixed / Removed / Documented / Planned).
Julkaisussa nimeä [Unreleased] uudelleen uudeksi [x.y.z] - YYYY-MM-DD, aloita uusi [Unreleased], nosta version tiedostossa Cargo.toml (jotta tulos-JSONin engine_version vastaa), päivitä vertailulinkit alareunassa ja lisää tagi vx.y.z.
Pidä merkinnät ytimekkäinä ja käyttäjälähtöisinä; linkitä issuet/PR:t, kun siitä on hyötyä.

Pull request, joka muuttaa käyttäytymistä ilman changelog-merkintää, on keskeneräinen.

Vientivalvonta#

PNT-kestävyys ja kvanttianturointi voivat sivuta kaksikäyttötuotteiden vientivalvontaa. Pidä julkinen repositorio yleisissä, julkaistuissa malleissa ja menetelmissä. Kaikki vientiarkaluonteista kestävyys-/harhautuksenestosyvyyttä muistuttava kuuluu yksityiseen overlayhin, ei tänne. Jos olet epävarma, kysy ennen kontribuutiota.

Lisenssi#

Kshana on kaksoislisensoitu (AGPL-3.0 tai kaupallinen lisenssi, jonka myöntää Ashforde OÜ — ks. LICENSING.md). Jotta tämä toimisi edelleen, kontribuutioiden on oltava käytettävissä molempien lisenssien alla. Siksi kontribuoimalla hyväksyt, että:

kontribuutiosi lisensoidaan sisääntulevana lisenssillä AGPL-3.0-only; ja
myönnät myös yhtiölle Ashforde OÜ pysyvän, maailmanlaajuisen, rojaltittoman, peruuttamattoman lisenssin käyttää, muokata ja lisensoida uudelleen kontribuutiosi osana Kshanan kaupallisesti lisensoitua versiota (eli jakaa se myös muilla kuin AGPL-pohjaisilla kaupallisilla ehdoilla). Säilytät tekijänoikeuden kontribuutioosi.

Tämä kevyt kaksoislisenssimyöntö — ei tekijänoikeuden luovutus — mahdollistaa sen, että projekti pysyy avoimena ja tarjoaa kaupallisen version. Jos et voi myöntää kohtaa (2) (esimerkiksi työnantajan omistama koodi), sano se pull requestissasi ennen kontribuutiota.

Poikkeus: integrations/opencpn/plugin/. Tämä hakemisto on lisensoitu GPL-3.0-or-later (ks. sen LICENSE) eikä kuulu kaupallisen lisenssin piiriin. Sen kontribuutiot lisensoidaan sisääntulevina vain GPL-3.0-or-later-lisenssillä; myöntö (2) ei koske niitä.

Allekirjoita jokainen commit (sign-off) ja vahvista siten Developer Certificate of Origin: git commit -s (lisää rivin Signed-off-by).