Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (93 loc) · 13.1 KB

CONTRIBUTING.md

File metadata and controls

138 lines (93 loc) · 13.1 KB
Raw

Contributing to Kiyome / Kiyomeへの貢献

Kiyomeへの関心をありがとうございます。現在は0.1.0-alpha.1で、実ストレージ向けコードを含む一方、QEMU E2Eと機種別HIL（実機）試験は未完了です。小さな表示変更でもwrong-target erasureやfalse-success reportにつながり得るため、通常のapplicationより慎重なreviewを行います。

Thank you for contributing. Kiyome is currently 0.1.0-alpha.1: real-device code exists, while QEMU E2E and model-specific hardware-in-the-loop (HIL) validation are incomplete. Even a small UI change can contribute to wrong-target erasure or a false-success report, so changes receive stricter review than an ordinary application.

最初に読むもの / Read first

脆弱性、wrong-target primitive、confirmation/protection bypass、未消去を成功にする問題はpublic Issueへ書かず、SECURITY.mdの非公開手順を使ってください。実reportにはserial等が含まれるため、通常のbug reportにも無加工で添付しないでください。

Do not disclose a vulnerability, wrong-target primitive, confirmation/protection bypass, or false-success condition in a public issue. Follow the private process in SECURITY.md. Real reports contain serials and other identifiers; do not attach them unredacted to ordinary bug reports either.

開発環境 / Development setup

Node.js 20以上を使います。runtime npm dependencyはありませんが、lockfileどおりに環境を確認してください。

Use Node.js 20 or later. There are no runtime npm dependencies, but use the lockfile when preparing the environment.

npm ci --ignore-scripts --no-audit --no-fund
npm run check
npm test

LinuxではCIと同じShellCheckも実行します。

On Linux, run the same ShellCheck coverage as CI:

shellcheck scripts/*.sh live/auto/config live/config/hooks/live/*.hook.chroot \
  live/config/includes.chroot/usr/local/bin/kiyome \
  live/config/includes.chroot/usr/local/bin/kiyome-console

対話UIは安全なdemoから試せます。

Start UI work in the safe demo:

npm run demo
node ./bin/kiyome.mjs inventory --demo --json

ISO/QEMU手順はBUILD.md / BUILD.en.mdを参照してください。shell scriptとLive hook/wrapperのGit executable bitも保持してください。

See BUILD.md / BUILD.en.md for ISO and QEMU procedures. Preserve Git executable bits on shell scripts and Live hooks/wrappers.

安全不変条件 / Safety invariants

次を弱めるchangeはmerge対象になりません。意図的なredesignなら、同等以上の安全性を示すthreat model、test、reviewが必要です。

Changes must not weaken the following invariants. An intentional redesign needs a threat model, tests, and review demonstrating equal or stronger safety.

  1. 実消去はKiyome Live marker、root、解決済みboot source、write/fsync可能な一意のlog volumeを要求する。Real erasure requires the Kiyome Live marker, root, a resolved boot source, and exactly one writable/fsync-capable log volume.
  2. boot/log媒体、protected mount、mounted/read-only/non-disk target、low/duplicate identity、共有・remote・未解決transportはblockする。Block boot/log media, protected mounts, mounted/read-only/non-disk targets, low-confidence or duplicate identities, and shared, remote, or unresolved transports.
  3. operatorはmodel、serial、容量、method、native scopeを見たうえでplan固有phraseを手入力し、直前countdownを通る。The operator sees model, serial, capacity, method, and native scope, then types the plan-specific phrase and passes the final countdown.
  4. 破壊command前にfresh inventory、identity、capability、mount、scope、log volumeを再検査する。Recheck fresh inventory, identity, capabilities, mounts, scope, and log volume before the destructive command.
  5. mutableな/dev/sdX名だけを信用せず、可能な限りkernel device objectをpinする。Do not rely only on mutable /dev/sdX names; pin the kernel device object where possible.
  6. 不明なcapability、scope、submission、status、completionはsuccessではなくblockまたはindeterminateにする。Unknown capability, scope, submission, status, or completion must block execution or produce indeterminate, never success.
  7. backend successと監査保存成功を分離する。reportPersisted=falseを完了扱いしない。Keep backend success separate from audit persistence; never treat reportPersisted=false as complete.
  8. COMPLETEDはfinal artifact/indexをcommitした後の最後のmarker writeとする。markerなしrunに加え、NVMe/ATAでは明示的に安全なterminal evidence pairを持たないcompleted runもfail-closedで全新規実行をblockする。Write COMPLETED last after final artifacts/indexes. Fail closed on every unmarked run and on every completed NVMe/ATA run that lacks an explicitly safe terminal-evidence pair.
  9. controller-native操作を、確実にcancelできるようには表示しない。Do not present controller-native operations as cancellable when cancellation cannot be guaranteed.
  10. 無人の破壊的CLI、network API、外部profileからの自動実行をalphaへ追加しない。Do not add an unattended destructive CLI, network API, or automatic execution from an external profile to the alpha.

external utilityは固定したexecutable候補とargument arrayでspawn(..., {shell:false})する設計を保ってください。device path、serial、log data等をshell command stringへ連結しないでください。writable USB上のprogram/configをrootで自動実行する機能も追加しないでください。

Keep external utilities on fixed executable candidates and argument arrays with spawn(..., {shell:false}). Never concatenate device paths, serials, log data, or similar values into a shell command string. Do not add root auto-execution of programs or configuration from the writable USB.

消去methodを追加・変更する場合 / Adding or changing a method

PRには少なくとも次を含めてください。

A method PR must include at least:

  • 対象media/transportと除外scope。Supported media/transports and excluded scope.
  • authoritative specificationまたはtoolの一次資料と、実際に使うversion/argument。Primary specification or tool documentation and the exact tested version/arguments.
  • capability probeがunknown/errorをfail closedにすること。A capability probe that fails closed on unknown/error states.
  • native operation scope（device/namespace/controller/subsystem）と、保護対象へ広がらないことの検査。Definition and validation of native operation scope—device, namespace, controller, or subsystem—so it cannot expand onto protected targets.
  • command submission、進捗、完了、verificationを区別するevidence。Evidence distinguishing command submission, progress, completion, and verification.
  • timeout、hotplug、tool crash、status parse failure、power loss時のresult semantics。Result semantics for timeout, hotplug, tool crash, status-parse failure, and power loss.
  • cancel可否を正確に表すUIとdocumentation。UI and documentation that accurately state cancellation behavior.
  • unit fixture、QEMUで可能なnegative test、隔離した廃棄可能hardwareのHIL record。Unit fixtures, feasible negative tests in QEMU, and HIL records from isolated expendable hardware.
  • METHODS、SAFETY、日英catalog、report evidence contractの同時更新。Matching updates to Methods, Safety, both language catalogs, and the report evidence contract.

“DoD certified”、“NIST approved recipe”、“military grade”等の表現は使わないでください。historical pattern名と、現在のClear/Purge/Destroy outcome mappingを区別してください。

Do not use claims such as “DoD certified,” “NIST-approved recipe,” or “military grade.” Distinguish historical pattern names from current outcome mappings such as Clear/Purge/Destroy.

report/schema変更 / Report and schema changes

reportはpublic interfaceです。fieldの削除・意味変更を黙って行わないでください。

The report is a public interface. Do not silently remove fields or change their meaning.

  • compatibleなfield追加でもschema、REPORT_FORMAT、fixture/testを更新する。For compatible field additions, update the schema, Report Format, fixtures, and tests.
  • incompatible変更は新しいschema ID/versionとmigration/consumer方針を提案する。For incompatible changes, propose a new schema ID/version and a migration/consumer policy.
  • JSON Schemaだけでなくresult/verification/persistenceのsemantic testを追加する。Add semantic tests for result, verification, and persistence, not just JSON Schema checks.
  • checksum対象、payload hash、history chain、finalization順序を変える場合は、電源断/failure injection testを含める。Changes to checksum scope, payload hashing, history chains, or finalization ordering need power-loss/failure-injection tests.
  • success、summary、100%表示を、backend evidenceとreport persistenceより先に確定しない。Do not finalize success, summaries, or a 100% display before backend evidence and report persistence.

UI/i18n変更 / UI and i18n changes

日本語とEnglish catalogのkey parity testを維持し、80x24で重要情報とconfirmationが読めることを確認してください。色だけでprotected/warning/resultを表さず、terminal width、CJK幅、framebufferなしのEnglish fallbackも考慮してください。

Keep Japanese and English catalog keys in parity and confirm that critical identity/confirmation information remains readable at 80x24. Do not convey protection, warnings, or results by color alone. Account for terminal width, CJK display width, and the English fallback without a framebuffer.

testの段階 / Test ladder

  1. unit testとfixtureだけで開始する。Start with unit tests and fixtures.
  2. demoでreal block device commandが一切発行されないことを確認する。Confirm demo emits no real block-device command.
  3. file-backedで廃棄可能なQEMU labを使う。Use the expendable file-backed QEMU lab.
  4. HILが必要な場合だけ、明示的なtest planと独立reviewのもとで、組織が所有する廃棄可能媒体を隔離hostに接続する。Only when HIL is necessary, connect organization-owned expendable media to an isolated host under an explicit test plan and independent review.

HIL hostから非対象diskを物理的に外し、model、firmware、transport/bridge、容量、method、期待scope、tool/package version、result、power-cycle後の確認を記録してください。個人device、第三者device、唯一のcopy、production assetは使わないでください。実行した事実だけで「対応済み」にせず、negative caseとrecoveryも確認してください。

Disconnect non-target disks from an HIL host. Record model, firmware, transport/bridge, capacity, method, expected scope, tool/package versions, result, and post-power-cycle checks. Never use personal devices, third-party devices, the only copy of data, or production assets. A single successful execution is not support validation; test negative cases and recovery as well.

Pull request checklist

  • Changeのrisk、threat modelへの影響、failure時の挙動を説明した / The risk, threat-model impact, and failure behavior are explained.
  • npm run checkとnpm testが成功した / npm run check and npm test pass.
  • 関係するshell scriptはShellCheckを通した / Relevant shell scripts pass ShellCheck.
  • safety invariantと無人破壊CLI禁止を維持した / Safety invariants and the no-unattended-destructive-CLI rule remain intact.
  • 日英UI/documentationを揃えた / Japanese and English UI/documentation match.
  • report/schema compatibilityを検討しtestした / Report/schema compatibility was considered and tested.
  • QEMU/HILを実施した範囲と未検証範囲を明記した / QEMU/HIL coverage and untested scope are explicit.
  • 実serial、WWN、NQN、SMART、engine log等をredactした / Real serials, WWNs, NQNs, SMART data, and engine logs are redacted.
  • 規格認証や実機対応を過大に主張していない / No standards certification or hardware support is overstated.

小さく、review可能なPRを歓迎します。安全に関するassumptionを隠さず、分からない状態をindeterminateとして扱うchangeほど、Kiyomeらしい貢献です。

Small, reviewable PRs are welcome. State safety assumptions explicitly; changes that preserve uncertainty as indeterminate are especially aligned with Kiyome's design.