Masintõlge, mida emakeelne kõneleja pole üle vaadanud. Võrdlusallikaks on ingliskeelne versioon.

ProjektMuuda GitHubisAllikas: CONTRIBUTING.md

Kshana arendusse panustamine

Täname huvi eest. Kshana eesmärk on olla neutraalne, reprodutseeritav, ausalt valideeritud etalon hübriidse kvant/klassikalise PNT jaoks. Panuste suhtes kehtib see lävi: korrektsus, viited ja reprodutseeritavus on olulisemad kui laius.

Kuidas projekti juhitakse — kes otsustab, tehniline lävi ning avatud/suletud piir — on dokumenteeritud failis GOVERNANCE.md.

Arendus#

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

Valikulised keelesidestused on funktsiooniga blokeeritud ja vaikimisi väljas (nii et ülaltoodud ehitus ja sõltuvusauditi lüüs neid kunagi ei puuduta). Nendega töötamiseks:

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

Enne iga commit’i — kiire tsükkel#

Need võtavad sekundeid. Need on faili ci.yml töö check alamhulk samas järjekorras, nii et siinne tõrge on seal tõrge:

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
  • Reprodutseeritavus on range invariant. Muudatus, mis muudab (scenario, seed, version) mittedeterministlikuks, on viga. Juhuslikkus peab voolama algväärtustatud RNG kaudu; kvant- ja klassikalised käitused kasutavad sõltumatuid, deterministlikult tuletatud algväärtusi.
  • Hoidla hügieen. Commit’id ja sisu ei tohi kanda automaatse tööriista omistamise lõppe ega jalusi ning ei tohi nimetada tehisintellekti assistenti autorina kusagil sisus, failinimedes ega ajaloos. Kaitse jõustab seda.

Enne push’i — täielik lüüs#

scripts/gate.sh on kanooniline lüüs: see käitab cargo test --all lühendamata, seejärel scripts/check-repeatability.sh, et käitada teegi komplekt veel mõned korrad, sest lõimede läbipõimumise võidujooks on ühe käituse puhul nähtamatu. Ainult õnnestumise korral kirjutab see .gate-receipt.json (jälgimata — masina olek ühe käituse kohta, mitte sisu).

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?

See on tahtlikult aeglane — 62-79 minutit tervel püsiseisundil, faili scripts/gate.sh päise järgi, mis kannab praegust väärtust — ja ajalõppu ei ole, sest piisavalt lühike ajalõpp, et olla kasulik, tapaks tervisliku käituse. Alamhulga käitus, mis tuli roheline, ei ole lüüs: mõlemad defektid, mille jaoks see mehhanism on olemas, jõudsid selle kaudu läbi.

Panustajad, kes töötavad hargist, ei vaja kviitungi konksu — see on kohalik hooldaja lüüs ja CI on see, mis tegelikult tõmbepäringut lüüsib. gate.sh käitamine enne selle avamist tähendab lihtsalt, et CI ei ütle midagi, mida juba ei teataks.

Sensorimudeli lisamine või muutmine#

  1. Iga arvparameeter vajab päritolu. Viide tuleb panna mudeli stringi provenance ja stsenaariumifaili. Anonüümseid konstante pole.
  2. Valideeri standardse seose vastu, mitte ainult sisemise kooskõla vastu — nt Alani hälve kellade jaoks, Grovesi dead-reckoning’u vea kasv inertsiaalse jaoks, ajastuse→kaugusmõõtmise teisendus aja edastamiseks. Lisa test, mis kinnitab, et simuleeritud väljund taastoodab avaldatud/seose väärtuse määratud tolerantsi piires.
  3. Ole küpsuse osas aus. Olekuregister on src/verification.rs::verification_matrix() — lisa või muuda seal rida, nimeta selle väline sõltumatu etalon (või ütle selgelt, et seda pole, mis teeb selle tasemeks Modelled), seejärel genereeri avaldatud artefaktid uuesti käsuga cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md ja web/data/verification-matrix.json on kõik genereeritud sellest funktsioonist ja ütlevad põhjusega „ära redigeeri käsitsi“. Uuenda ka narratiivi docs/VALIDATION.md, kui proosa seda vajab, ning märgi sihtmärgid või maapealsete demonstraatorite tulemused sellisena.

Testid#

  • Testipõhine: kirjuta kõigepealt ebaõnnestuv test, oodatava väärtusega, mis on füüsikast/seosest käsitsi tuletatud enne realiseerimist.
  • Deterministlikud testid kinnitavad täpseid (käsitsi tuletatud) väärtusi; statistilised testid kinnitavad määratud tolerantsi ja ideaalis keskmistavad algväärtuste üle hajuvuse kontrollimiseks.

Commit’id ja versioonimine#

  • Conventional Commits (feat:, fix:, docs:, test:, chore: …).
  • Semantic Versioning. Enne 1.0 võib stsenaariumi/tulemuse skeem muutuda; too lagunevad muudatused selgelt esile.
  • Väljalasked lõigatakse sildiga vX.Y.Z ja avaldamine on automaatne, kuid järjestatud. Auto-tag töövoog lükkab sildi, kui CI on rohelise versioonitõusu korral harus main. Release töövoog käitab sildistatud commit’il täieliku kontrolli ja ainult siis, kui see läbib, avaldab see crates.io-sse, Python Package Index’isse (PyPI), npm-i, ghcr.io-sse, Model Context Protocol (MCP) registrisse ja JetBrains Marketplace’i; seejärel kontrollib see, et iga kanal serveerib versiooni, ja ehitab sildist uuesti kshana.dev. Keegi ei käivita cargo publish käsitsi. Sammud ja ebaõnnestunud avaldamise uuesti proovimine on failis docs/RELEASING.md.

Muudatuste logi hooldus (nõutav)#

Iga kasutajale nähtav muudatus uuendab faili CHANGELOG.md:

  1. Lisa kirje jaotise [Unreleased] alla õigesse gruppi (Added / Changed / Fixed / Removed / Documented / Planned).
  2. Väljalaskel nimeta [Unreleased] ümber uueks [x.y.z] - YYYY-MM-DD, alusta värsket [Unreleased], tõsta version failis Cargo.toml (et engine_version tulemuse JSON-is ühtiks), uuenda alumisi võrdluslinke ja sildista vx.y.z.
  3. Hoia kirjed lühikesed ja kasutajale suunatud; lingi probleeme/PR-e, kus see on kasulik.

Tõmbepäring, mis muudab käitumist ilma muudatuste logi kirjeta, on poolik.

Ekspordikontroll#

PNT vastupidavus ja kvantandurdus võivad puutuda kahese kasutusega ekspordikontrolli. Hoia avalik hoidla üldiste, avaldatud mudelite ja meetodite juures. Kõik, mis meenutab ekspordi suhtes tundlikku vastupidavuse/spuufimisvastast sügavust, kuulub privaatsele kihile, mitte siia. Kahtluse korral tuleb enne panustamist küsida.

Litsents#

Kshana on kahe litsentsiga (AGPL-3.0 või Ashforde OÜ kommertslitsents — vt LICENSING.md). Et see jätkuvalt töötaks, peavad panused olema kasutatavad mõlema litsentsi all. Seega panustades nõustutakse, et:

  1. panus on litsentsitud sissetulevalt AGPL-3.0-only alusel; ja
  2. antakse ka Ashforde OÜ-le tähtajatu, ülemaailmne, tasuta, tühistamatu litsents kasutada, muuta ja panust uuesti litsentsida osana Kshana kommertslitsentsiga väljaandest (st levitada seda ka mitte-AGPL kommertstingimustel). Autoriõigus panusele jääb panustajale.

See kerge kahe litsentsi andmine — mitte autoriõiguse loovutamine — võimaldab projektil jääda avatuks ja pakkuda kommertsväljaannet. Kui andmine (2) ei ole võimalik (näiteks tööandjale kuuluv kood), tuleb sellest tõmbepäringus enne panustamist teada anda.

Erand: integrations/opencpn/plugin/. See kataloog on litsentsitud GPL-3.0-or-later alusel (vt selle LICENSE) ja jääb kommertslitsentsist välja. Panused sellesse on litsentsitud sissetulevalt ainult GPL-3.0-or-later alusel; andmine (2) neile ei kehti.

Allkirjasta iga commit, et kinnitada Developer Certificate of Origin: git commit -s (lisab rea Signed-off-by).