natsukium/felis
Watch
1
Code Issues 27 Pull requests 1 Projects Releases Packages Wiki Activity Actions

[v0.1/Proto Review] 1.0 の wire major/minor と BREAKING baseline を今決める #147

New issue
Closed
opened 2026-09-05 11:58:13 +09:00 by natsukium · 1 comment
natsukium commented 2026-09-05 11:58:13 +09:00
Owner
Copy link

背景

現行 crates/felis-protocol/src/preface.rs は PROTOCOL_MAJOR = 1, PROTOCOL_MINOR = 9 で 1.0 リリース前の pre-release 段階にもかかわらず minor が 9 まで積み上がっている。docs/reference/ipc.md The minor ledger には 0..9 の全 row が記載され、BREAKING.md には first-release 行が残る。

#12 の Contract freeze boundary は「first tag で preface, protobuf schema, row codec, evolution rules を凍結」と定義し、#30 は「全 wire 編集後に protocol 2.0 へ reset」を要求している。しかし現行の 1.9 は「1.0 で公開するなら 1.0 が最初の stable major になるはず」という期待とずれる:

  • reference/workspace.md Versioning は BuildIdentity <version> (<revision>) を 0.1.0 で統一しているが、wire major は 1 のまま。
  • CHANGELOG.md は Unreleased のみで、wire 1.9 がどの tag から public か不明。
  • BREAKING.md の first-release は release baseline がない間の暫定表現で、#115 が release workflow を持つまで有効。1.0 までに proto-baseline/ を commit するか、BREAKING.md を base: <sha> に置き換えるか決める必要がある。

さらに PROTOCOL_MINOR = 9 の ledger は 1.0 前の breaking を minor として積んだ履歴であり、1.0 公開後に「1.9 からの additive のみが minor」になる。1.0 で PROTOCOL_MINOR を 0 に reset せず 9 のまま tag すると、1.0 の user が minor 9 を「1.0 の新機能」と誤読する。

問い

1.0 で以下を決める:

  1. wire major を 1 のまま 1.0 を切るか、2.0 に bump して #30 の意図通り「breaking を跨いだ clean baseline」として公開するか。
  2. PROTOCOL_MINOR を 9 のまま tag するか、0 に reset して 1.0 の ledger を 0: base schema のみにし、既存の 1..9 を explanation/architecture/ipc.md の history として退避するか。
  3. BREAKING.md の first-release を base: <tag-sha> / proto-baseline/ のどちらで置き換え、just proto-compat が tag 後にどの baseline と比較するか。

提案

  • 案A (現行維持): wire 1.9 のまま v0.1.0 を切る。BREAKING.md の first-release を v0.1.0 tag 時点で base: <v0.1.0-sha> に置き換え、以後の breaking は BREAKING.md に base 行を追加する運用。PROTOCOL_MINOR は 9 のまま frozen とし、reference/ipc.md ledger は 0..9 を v0.1.0 の ledger として凍結。
  • 案B (clean baseline, 推奨): #30 の意図通り 1.0 で PROTOCOL_MAJOR = 2, PROTOCOL_MINOR = 0 に bump。既存の 1.1..1.9 の ledger は explanation/architecture/ipc.md「Pre-release history」に退避し、reference/ipc.md ledger は 2.0: base schema のみに reset。BREAKING.md は proto-baseline/ を v0.1.0 の proto snapshot で初期化し、first-release 行を削除。just proto-compat は proto-baseline/ との比較に切り替える。

案B は「1.0 の ledger が additive のみ」という純度が高いが、SUPPORTED_MAJOR_MIN/MAX = 1 の deprecation window を持つコードが 2 に変わるため、preface.rs の SUPPORTED_MAJOR_MIN / MAX と MINOR_LEDGER のテストが 1.0 で一括変更になる。案A は変更が最小だが、ledger が pre-release の breaking を additive と混在させたまま frozen になる。

判定基準

  • v0.1.0 tag 時の PROTOCOL_MAJOR.MINOR が reference/ipc.md ledger 先頭行と preface.rs MINOR_LEDGER 先頭要素で一致し、cargo test -p felis-protocol の the_protocol_version_matches_the_schema が green であること。
  • BREAKING.md が first-release / base: <sha> / proto-baseline/ のいずれかで 1.0 の baseline を一意に指し、just proto-compat が tag 後に baseline との比較で green であること。
  • CHANGELOG.md v0.1.0 entry に wire バージョンが明記され、skills/felis の version 記述と一致すること。

対象ファイル

  • crates/felis-protocol/src/preface.rs (PROTOCOL_MAJOR, PROTOCOL_MINOR, MINOR_LEDGER, SUPPORTED_MAJOR_MIN/MAX)
  • crates/felis-protocol/proto/felis.proto (package felis.v1 の version コメント)
  • crates/felis-protocol/proto/BREAKING.md (first-release / base: / proto-baseline/)
  • docs/reference/ipc.md「Versioning」「The minor ledger」
  • docs/reference/workspace.md「Versioning」
  • CHANGELOG.md (Unreleased → v0.1.0)

Parent: #12 および #30 / #52

## 背景 現行 ` crates/felis-protocol/src/preface.rs` は `PROTOCOL_MAJOR = 1`, `PROTOCOL_MINOR = 9` で 1.0 リリース前の pre-release 段階にもかかわらず minor が 9 まで積み上がっている。`docs/reference/ipc.md` The minor ledger には 0..9 の全 row が記載され、`BREAKING.md` には `first-release` 行が残る。 `#12` の Contract freeze boundary は「first tag で preface, protobuf schema, row codec, evolution rules を凍結」と定義し、`#30` は「全 wire 編集後に protocol 2.0 へ reset」を要求している。しかし現行の 1.9 は「1.0 で公開するなら 1.0 が最初の stable major になるはず」という期待とずれる: - `reference/workspace.md` Versioning は `BuildIdentity <version> (<revision>)` を `0.1.0` で統一しているが、wire major は `1` のまま。 - `CHANGELOG.md` は `Unreleased` のみで、wire 1.9 がどの tag から public か不明。 - `BREAKING.md` の `first-release` は release baseline がない間の暫定表現で、`#115` が release workflow を持つまで有効。1.0 までに `proto-baseline/` を commit するか、`BREAKING.md` を `base: <sha>` に置き換えるか決める必要がある。 さらに `PROTOCOL_MINOR = 9` の ledger は 1.0 前の breaking を minor として積んだ履歴であり、1.0 公開後に「1.9 からの additive のみが minor」になる。1.0 で `PROTOCOL_MINOR` を `0` に reset せず 9 のまま tag すると、1.0 の user が `minor 9` を「1.0 の新機能」と誤読する。 ## 問い 1.0 で以下を決める: 1. wire major を `1` のまま `1.0` を切るか、`2.0` に bump して `#30` の意図通り「breaking を跨いだ clean baseline」として公開するか。 2. `PROTOCOL_MINOR` を `9` のまま tag するか、`0` に reset して 1.0 の ledger を `0: base schema` のみにし、既存の 1..9 を `explanation/architecture/ipc.md` の history として退避するか。 3. `BREAKING.md` の `first-release` を `base: <tag-sha>` / `proto-baseline/` のどちらで置き換え、`just proto-compat` が tag 後にどの baseline と比較するか。 ## 提案 - **案A (現行維持)**: wire `1.9` のまま `v0.1.0` を切る。`BREAKING.md` の `first-release` を `v0.1.0` tag 時点で `base: <v0.1.0-sha>` に置き換え、以後の breaking は `BREAKING.md` に `base` 行を追加する運用。`PROTOCOL_MINOR` は 9 のまま frozen とし、`reference/ipc.md` ledger は 0..9 を v0.1.0 の ledger として凍結。 - **案B (clean baseline, 推奨)**: `#30` の意図通り 1.0 で `PROTOCOL_MAJOR = 2`, `PROTOCOL_MINOR = 0` に bump。既存の 1.1..1.9 の ledger は `explanation/architecture/ipc.md`「Pre-release history」に退避し、`reference/ipc.md` ledger は `2.0: base schema` のみに reset。`BREAKING.md` は `proto-baseline/` を v0.1.0 の proto snapshot で初期化し、`first-release` 行を削除。`just proto-compat` は `proto-baseline/` との比較に切り替える。 案B は「1.0 の ledger が additive のみ」という純度が高いが、`SUPPORTED_MAJOR_MIN/MAX = 1` の deprecation window を持つコードが `2` に変わるため、`preface.rs` の `SUPPORTED_MAJOR_MIN` / `MAX` と `MINOR_LEDGER` のテストが 1.0 で一括変更になる。案A は変更が最小だが、ledger が pre-release の breaking を additive と混在させたまま frozen になる。 ## 判定基準 - `v0.1.0` tag 時の `PROTOCOL_MAJOR.MINOR` が `reference/ipc.md` ledger 先頭行と `preface.rs` `MINOR_LEDGER` 先頭要素で一致し、`cargo test -p felis-protocol` の `the_protocol_version_matches_the_schema` が green であること。 - `BREAKING.md` が `first-release` / `base: <sha>` / `proto-baseline/` のいずれかで 1.0 の baseline を一意に指し、`just proto-compat` が tag 後に baseline との比較で green であること。 - `CHANGELOG.md` `v0.1.0` entry に wire バージョンが明記され、`skills/felis` の version 記述と一致すること。 ## 対象ファイル - `crates/felis-protocol/src/preface.rs` (`PROTOCOL_MAJOR`, `PROTOCOL_MINOR`, `MINOR_LEDGER`, `SUPPORTED_MAJOR_MIN/MAX`) - `crates/felis-protocol/proto/felis.proto` (package `felis.v1` の version コメント) - `crates/felis-protocol/proto/BREAKING.md` (`first-release` / `base:` / `proto-baseline/`) - `docs/reference/ipc.md`「Versioning」「The minor ledger」 - `docs/reference/workspace.md`「Versioning」 - `CHANGELOG.md` (`Unreleased` → `v0.1.0`) Parent: #12 および #30 / #52
natsukium commented 2026-09-05 12:11:19 +09:00
Author
Owner
Copy link

Triage (2026-09-05)

Already decided. f56f5529 (protocol: reset wire-break baseline to 1.0, the #138 decision) keeps PROTOCOL_MAJOR = 1 / PROTOCOL_MINOR = 9, freezes the ledger at 0..9, and leaves first-release in BREAKING.md until #115 gives the tag path a committed baseline. That is option A of this issue, question by question:

  1. major stays 1; the 2.0 reset (#30) was dropped.
  2. minor stays 9; the ledger is the v0.1.0 ledger.
  3. first-release until the post-release baseline commit, owned by #115.

Closing as resolved. The remaining loose end is the #12 body, which still describes #30 as a 2.0 reset; a correction is posted on #12.

## Triage (2026-09-05) Already decided. `f56f5529` (protocol: reset wire-break baseline to 1.0, the #138 decision) keeps `PROTOCOL_MAJOR = 1` / `PROTOCOL_MINOR = 9`, freezes the ledger at 0..9, and leaves `first-release` in `BREAKING.md` until #115 gives the tag path a committed baseline. That is option A of this issue, question by question: 1. major stays 1; the 2.0 reset (#30) was dropped. 2. minor stays 9; the ledger is the v0.1.0 ledger. 3. `first-release` until the post-release baseline commit, owned by #115. Closing as resolved. The remaining loose end is the #12 body, which still describes #30 as a 2.0 reset; a correction is posted on #12.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
ci/darwin-smoke
No results found.
Labels
Clear labels   
priority/P0
Must be resolved before the v0.1.0 tag

  
priority/P1
Must be settled before the first public contract freezes

  
priority/P2
Explicitly deferred until after v0.1.0

  
release/v0.1.0
Work tracked for the first tagged release

  
status/blocked
Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  
status/planned
Triaged with a source-grounded plan and a passed pi review; ready to implement

  
type/bug
Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  
type/design
An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  
type/test-gap
Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  
type/tracker
Parent issue that tracks child work

No labels
priority/P0
priority/P1
priority/P2
release/v0.1.0
status/blocked
status/planned
type/bug
type/design
type/test-gap
type/tracker
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
natsukium/felis#147
No description provided.