Внесок у 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

Перед кожним комітом — швидкий цикл#

Вони займають секунди. Це підмножина завдання check з ci.yml в тому самому порядку, тож збій тут — це збій там:

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) стає недетермінованим, є вадою. Випадковість має йти через зерновий ГВЧ (RNG); квантові та класичні прогони використовують незалежні, детерміновано виведені зерна.
• Гігієна репозиторію. Коміти та вміст не повинні містити завершальних рядків чи приміток з позначенням автоматизованих інструментів і не повинні називати ШІ-помічника автором ніде у вмісті, назвах файлів чи історії. Це забезпечує сторожова перевірка.

Перед надсиланням — повна перевірка#

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, який містить поточний показник — і не має тайм-ауту, бо тайм-аут, достатньо короткий, щоб бути корисним, обірвав би здоровий прогін. Прогін підмножини, що завершився зеленим, не є перевіркою: обидві вади, для яких існує цей механізм, дісталися до неї саме так.

Учасникам, що працюють із форка, гачок квитанції не потрібен — це локальна перевірка супровідника, а запит на злиття насправді перевіряє CI. Запуск gate.sh перед його відкриттям просто означає, що CI не повідомить вам нічого, чого ви ще не знали.

Додавання чи зміна моделі сенсора#

1. Кожен числовий параметр потребує походження. Вкажіть цитування в рядку provenance моделі та у файлі сценарію. Жодних анонімних констант.
2. Перевіряйте за стандартним співвідношенням, а не лише за внутрішньою узгодженістю — наприклад, девіація Аллана для годинників, закон зростання похибки інерційної навігації Groves для інерційних сенсорів, перетворення часу на дальність для передавання часу. Додайте тест, що змодельований вихід відтворює опубліковане/співвідношення значення в межах визначеного допуску.
3. Будьте чесними щодо зрілості. Реєстр станів — це src/verification.rs::verification_matrix(): додайте чи змініть там рядок, назвіть його зовнішній оракул (або прямо скажіть, що його немає, і тоді це 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, а публікація автоматична, але впорядкована. Робочий процес Auto-tag надсилає тег, щойно CI зелений на main після підвищення версії. Робочий процес Release виконує повну перевірку на позначеному коміті й лише в разі успіху публікує в crates.io, Python Package Index (PyPI), npm, ghcr.io, реєстр Model Context Protocol (MCP) і JetBrains Marketplace; потім перевіряє, що кожен канал віддає цю версію, і перебудовує kshana.dev із тега. Ніхто не запускає cargo publish вручну. Кроки та спосіб повторити невдалу публікацію описано в docs/RELEASING.md.

Ведення журналу змін (обов'язково)#

Кожна помітна користувачеві зміна оновлює CHANGELOG.md:

1. Додайте запис у розділі [Unreleased], у правильній групі (Added / Changed / Fixed / Removed / Documented / Planned).
2. Під час випуску перейменуйте [Unreleased] на нове [x.y.z] - YYYY-MM-DD, почніть свіжий [Unreleased], підвищте version у Cargo.toml (щоб engine_version у JSON результату збігалося), оновіть посилання порівняння внизу та позначте тегом vx.y.z.
3. Тримайте записи стислими й орієнтованими на користувача; посилайтеся на задачі/запити на злиття, де це корисно.

Запит на злиття, що змінює поведінку без запису в журналі змін, неповний.

Експортний контроль#

Стійкість PNT і квантове сенсорство можуть підпадати під експортний контроль подвійного призначення. Обмежуйте публічний репозиторій загальними опублікованими моделями та методами. Усе, що нагадує експортно чутливу глибину стійкості/протидії спуфінгу, належить до приватного шару, а не сюди. Якщо не впевнені, запитайте, перш ніж робити такий внесок.

Ліцензія#

Kshana має подвійне ліцензування (AGPL-3.0 або комерційна ліцензія від Ashforde OÜ — див. LICENSING.md). Щоб це продовжувало працювати, внески мають бути придатними до використання за обома ліцензіями. Тож, роблячи внесок, ви погоджуєтеся, що:

1. ваш внесок ліцензується на вході за AGPL-3.0-only; і
2. ви також надаєте Ashforde OÜ безстрокову, всесвітню, безоплатну, безвідкличну ліцензію на використання, зміну та повторне ліцензування вашого внеску у складі комерційно ліцензованого видання Kshana (тобто також на розповсюдження за комерційними умовами, відмінними від AGPL). Авторське право на ваш внесок залишається за вами.

Це полегшене подвійне ліцензійне надання — не відчуження авторського права — дає змогу проєкту залишатися відкритим і пропонувати комерційне видання. Якщо ви не можете надати (2) (наприклад, код належить роботодавцю), скажіть про це у своєму запиті на злиття, перш ніж робити внесок.

Виняток: integrations/opencpn/plugin/. Ця тека ліцензується за GPL-3.0-or-later (див. її LICENSE) і лежить поза комерційною ліцензією. Внески до неї ліцензуються на вході лише за GPL-3.0-or-later; надання (2) на них не поширюється.

Підписуйте кожен коміт, щоб засвідчити Developer Certificate of Origin: git commit -s (додає рядок Signed-off-by).