Machinevertaling, niet beoordeeld door een moedertaalspreker. Engels is de referentie.

ProjectBewerken op GitHubBron: CONTRIBUTING.md

Bijdragen aan Kshana

Bedankt voor uw interesse. Kshana wil een neutrale, reproduceerbare, eerlijk getoetste referentie zijn voor hybride kwantum-/klassieke PNT. Bijdragen worden aan die drempel gehouden: juistheid, bronvermelding en reproduceerbaarheid gaan boven omvang.

Hoe het project wordt bestuurd — wie beslist, de technische drempel en de grens tussen open en gesloten — staat beschreven in GOVERNANCE.md.

Ontwikkeling#

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

De optionele taalbindingen zijn feature-gated en staan standaard uit (zodat de build hierboven en de poort voor de audit van afhankelijkheden ze nooit aanraken). Om eraan te werken:

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

Vóór elke commit — de snelle lus#

Deze duren seconden. Ze vormen een deelverzameling van de job check van ci.yml, in dezelfde volgorde, dus een fout hier is een fout daar:

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
  • Reproduceerbaarheid is een harde invariant. Een wijziging die (scenario, seed, version) niet-deterministisch maakt, is een bug. Toeval moet via de geseede RNG lopen; kwantum- en klassieke runs gebruiken onafhankelijke, deterministisch afgeleide seeds.
  • Hygiëne van de repository. Commits en inhoud mogen geen toeschrijvingsregels of voetteksten van geautomatiseerde tools bevatten en mogen nergens in inhoud, bestandsnamen of geschiedenis een AI-assistent als auteur noemen. De guard dwingt dit af.

Voordat u pusht — de volledige poort#

scripts/gate.sh is de canonieke poort: hij draait cargo test --all onverkort, en daarna scripts/check-repeatability.sh om de bibliotheeksuite nog een paar keer te herhalen, omdat een race door het verweven van threads bij één run onzichtbaar is. Alleen bij succes schrijft hij .gate-receipt.json (niet gevolgd — machinestatus over één run, geen inhoud).

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?

Hij is met opzet traag — 62-79 minuten in de gezonde stabiele toestand, volgens de kop van scripts/gate.sh, die het actuele cijfer bevat — en er is geen time-out, want een time-out die kort genoeg is om nuttig te zijn, zou een gezonde run afbreken. Een deelrun die groen terugkwam, is geen poort: beide defecten waarvoor dit mechanisme bestaat, kwamen er op die manier doorheen.

Bijdragers die vanuit een fork werken, hebben de receipt-hook niet nodig — het is een lokale poort voor beheerders, en CI is wat een pull request daadwerkelijk toelaat of tegenhoudt. Als u gate.sh draait voordat u er een opent, vertelt CI u simpelweg niets wat u nog niet wist.

Een sensormodel toevoegen of wijzigen#

  1. Elke numerieke parameter heeft herkomst nodig. Zet de bronvermelding in de tekenreeks provenance van het model en in het scenariobestand. Geen anonieme constanten.
  2. Toets aan de standaardrelatie, niet alleen aan interne consistentie — bijvoorbeeld de Allan-deviatie voor klokken, de foutgroei van koppelnavigatie volgens Groves voor inertiële sensoren, de omzetting van timing naar afstandsmeting voor tijdoverdracht. Voeg een test toe dat de gesimuleerde uitvoer de gepubliceerde waarde of relatiewaarde binnen een vastgelegde tolerantie reproduceert.
  3. Wees eerlijk over de maturiteit. Het statusregister is src/verification.rs::verification_matrix() — voeg de rij daar toe of wijzig haar, noem haar externe onafhankelijke referentie (of zeg ronduit dat er geen is, waardoor het Modelled wordt), en genereer daarna de gepubliceerde artefacten opnieuw met cargo run --bin gen_validation_artifacts. docs/VERIFICATION-MATRIX.md, docs/MODELLED-RATIONALE.md en web/data/verification-matrix.json worden allemaal uit die functie gegenereerd en zeggen niet voor niets "niet met de hand bewerken". Werk ook het verhaal in docs/VALIDATION.md bij wanneer de tekst dat nodig heeft, en label cijfers die doelen of resultaten van een demonstrator op de grond zijn als zodanig.

Tests#

  • Testgedreven: schrijf eerst de falende test, met de verwachte waarde met de hand afgeleid uit de fysica of relatie voordat u implementeert.
  • Deterministische tests toetsen exacte (met de hand afgeleide) waarden; statistische tests toetsen een vastgelegde tolerantie en middelen bij voorkeur over seeds om de spreiding te beheersen.

Commits en versiebeheer#

  • Conventional Commits (feat:, fix:, docs:, test:, chore: …).
  • Semantic Versioning. Vóór 1.0 kan het scenario-/resultaatschema veranderen; vermeld brekende wijzigingen expliciet.
  • Releases worden gemaakt met een tag vX.Y.Z, en publiceren is automatisch maar in vaste volgorde. De workflow Auto-tag pusht de tag zodra CI groen is op main bij een versieverhoging. De workflow Release draait de volledige verificatie op de getagde commit, en pas wanneer die slaagt, publiceert hij naar crates.io, de Python Package Index (PyPI), npm, ghcr.io, het Model Context Protocol-register (MCP) en de JetBrains Marketplace; daarna controleert hij of elk kanaal de versie aanbiedt en bouwt hij kshana.dev opnieuw op vanaf de tag. Niemand draait cargo publish met de hand. De stappen, en hoe u een mislukte publicatie opnieuw probeert, staan in docs/RELEASING.md.

Onderhoud van het changelog (verplicht)#

Elke voor gebruikers zichtbare wijziging werkt CHANGELOG.md bij:

  1. Voeg een item toe onder de sectie [Unreleased], in de juiste groep (Added / Changed / Fixed / Removed / Documented / Planned).
  2. Hernoem bij een release [Unreleased] naar de nieuwe [x.y.z] - YYYY-MM-DD, begin een nieuwe [Unreleased], verhoog de version in Cargo.toml (zodat engine_version in de resultaat-JSON overeenkomt), werk de vergelijkingslinks onderaan bij en tag vx.y.z.
  3. Houd items beknopt en gericht op gebruikers; link issues/PR's waar nuttig.

Een pull request dat gedrag wijzigt zonder item in het changelog is onvolledig.

Exportcontrole#

PNT-veerkracht en kwantumsensing kunnen raken aan exportcontroles voor producten voor tweeërlei gebruik. Houd de openbare repository bij generieke, gepubliceerde modellen en methoden. Alles wat lijkt op exportgevoelige diepgang in veerkracht of anti-spoofing hoort in de private overlay, niet hier. Vraag het bij twijfel voordat u het bijdraagt.

Licentie#

Kshana heeft een dubbele licentie (AGPL-3.0 of een commerciële licentie van Ashforde OÜ — zie LICENSING.md). Opdat dat blijft werken, moeten bijdragen onder beide licenties bruikbaar zijn. Door bij te dragen stemt u dus in met het volgende:

  1. uw bijdrage wordt inbound gelicentieerd onder de AGPL-3.0-only; en
  2. u verleent Ashforde OÜ ook een eeuwigdurende, wereldwijde, royaltyvrije, onherroepelijke licentie om uw bijdrage te gebruiken, te wijzigen en te herlicentiëren als onderdeel van de commercieel gelicentieerde editie van Kshana (dat wil zeggen om haar ook onder niet-AGPL commerciële voorwaarden te verspreiden). U behoudt het auteursrecht op uw bijdrage.

Deze lichte dubbele licentieverlening — geen overdracht van auteursrecht — maakt het mogelijk dat het project open blijft en een commerciële editie aanbiedt. Als u (2) niet kunt verlenen (bijvoorbeeld bij code die eigendom van een werkgever is), meld dat dan in uw pull request voordat u bijdraagt.

Uitzondering: integrations/opencpn/plugin/. Die map is gelicentieerd onder GPL-3.0-or-later (zie het bestand LICENSE) en valt buiten de commerciële licentie. Bijdragen eraan worden inbound gelicentieerd onder uitsluitend GPL-3.0-or-later; verlening (2) is er niet op van toepassing.

Onderteken elke commit om het Developer Certificate of Origin te bevestigen: git commit -s (voegt een regel Signed-off-by toe).