参与贡献Kshana

感谢你的关注。Kshana的目标是成为混合量子/经典PNT的一个中立、可复现、如实标注验证状态的参考。贡献须达到这一判据：正确性、引用出处和可复现性优先于覆盖面。

项目如何治理——由谁决定、技术判据，以及开放与封闭的边界——记录在GOVERNANCE.md中。

开发#

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

可选的语言绑定通过特性开关控制，默认关闭（因此上述构建和依赖审计关卡都不会触及它们）。要开发它们：

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

每次提交之前——快速循环#

这些只需几秒钟。它们是ci.yml的check作业的一个子集，顺序相同，因此在这里失败就是在那里失败：

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

可复现性是硬性不变量。任何使(scenario, seed, version)变得不确定的改动都是缺陷。随机性必须经由带种子的随机数发生器；量子和经典运行使用相互独立、由确定性方式派生的随机种子（seed）。
仓库规范。提交和内容不得带有自动化工具的署名尾注或页脚，也不得在内容、文件名或历史记录的任何地方将AI助手列为作者。守卫程序会强制执行这一点。

推送之前——完整关卡#

scripts/gate.sh是标准关卡：它先完整运行cargo test --all，再运行scripts/check-repeatability.sh，把库的测试套件多重跑几遍，因为线程交错导致的竞态在单次运行中是看不出来的。只有成功时它才会写出.gate-receipt.json（不纳入版本跟踪——这是关于某一次运行的机器状态，不是内容）。

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?

它是有意做得很慢的——健康的稳态下需62-79分钟，以scripts/gate.sh头部所注的当前数值为准——而且没有超时，因为短到有用的超时会杀掉一次健康的运行。仅运行子集并返回通过结果，不算关卡：这一机制所要防范的两类缺陷，都是这样通过的。

从复刻（fork）工作的贡献者不需要回执钩子——它是本地维护者的关卡，真正为拉取请求把关的是CI。在提交拉取请求之前运行gate.sh，只是意味着CI不会告诉你任何你尚不知道的事。

添加或修改传感器模型#

每个数值参数都需要出处。把引用写进模型的provenance字符串和场景文件中。不允许匿名常数。
对照标准关系式验证，而不只是内部自洽——例如时钟用阿伦偏差，惯性用Groves的航位推算误差增长，时间传递用授时到测距的换算。添加一项测试，检验仿真输出在所述容差内复现已发布的/关系式的值。
对成熟度保持诚实。状态登记表位于src/verification.rs::verification_matrix()——在那里添加或修改相应的行，写明其外部参考基准（oracle）（或明确说明没有，那就属于Modelled），然后用cargo run --bin gen_validation_artifacts重新生成发布的产物。docs/VERIFICATION-MATRIX.md、docs/MODELLED-RATIONALE.md和web/data/verification-matrix.json都由该函数生成，并且写着“请勿手工编辑”，这是有原因的。当文字叙述需要时，也要更新docs/VALIDATION.md，并将属于目标或地面演示结果的数据如实标明。

测试#

测试驱动：先写会失败的测试，其预期值须在实现之前由物理/关系式手工推导得出。
确定性测试断言精确的（手工推导的）值；统计性测试断言所述的容差，最好对多个随机种子取平均以控制离散。

提交与版本#

约定式提交（Conventional Commits）（feat:、fix:、docs:、test:、chore: ……）。
语义化版本。1.0之前，场景/结果的模式可能变化；请指明破坏性变更。
发布由vX.Y.Z标签触发，发布过程自动进行但有先后顺序。版本号提升后，一旦CI在main上通过，自动打标签工作流就会推送该标签。发布工作流在带标签的提交上运行完整验证，只有通过之后才会发布到crates.io、Python包索引（PyPI）、npm、ghcr.io、模型上下文协议（MCP）注册表和JetBrains Marketplace；随后它会检查每个渠道都提供该版本，并依据该标签重新构建kshana.dev。没有人手工运行cargo publish。具体步骤以及如何重试失败的发布，见docs/RELEASING.md。

变更日志维护（必须）#

每一项用户可见的变更都要更新CHANGELOG.md：

在[Unreleased]一节下，在合适的分组（Added / Changed / Fixed / Removed / Documented / Planned）中添加一条记录。
发布时，把[Unreleased]重命名为新的[x.y.z] - YYYY-MM-DD，新建一个[Unreleased]，提升Cargo.toml中的version（使结果JSON里的engine_version与之一致），更新底部的比较链接，并打上vx.y.z标签。
条目要简洁并面向用户；在有用之处链接议题/拉取请求。

如果拉取请求改变了行为却没有变更日志条目，则它是不完整的。

出口管制#

PNT韧性和量子传感可能涉及两用物项出口管制。公开仓库仅限于通用的、已发布的模型和方法。任何近似于涉及出口敏感的韧性/反欺骗深度内容，都属于私有叠加层，而不属于这里。如有疑问，请在贡献之前先询问。

许可证#

Kshana采用双重许可（AGPL-3.0 或来自Ashforde OÜ 的商业许可——见LICENSING.md）。为使其持续有效，贡献必须在两种许可之下都可使用。因此，通过贡献，你同意：

你的贡献按仅AGPL-3.0以入站方式授权；并且
你同时授予Ashforde OÜ一项永久的、全球范围的、免版税的、不可撤销的许可，可使用、修改，并将你的贡献作为Kshana商业许可版本的一部分重新授权（即也可依非AGPL的商业条款分发）。你保留对自己贡献的版权。

这项轻量的双重许可授权——不是版权转让——使项目既能保持开放，又能提供商业版本。如果你无法授予（2）（例如，雇主拥有的代码），请在贡献之前于你的拉取请求中说明。

例外：integrations/opencpn/plugin/。该目录采用GPL-3.0-or-later许可（见其LICENSE），不在商业许可范围之内。对它的贡献仅按GPL-3.0-or-later以入站方式授权；授权（2）不适用于这些贡献。

为每个提交签署（sign off），以证明遵守开发者原创证书（Developer Certificate of Origin）：git commit -s（会添加一行Signed-off-by）。