Hacktoberfest 2026：維護者為十月標記出來的 issue，仍然開放、適合新手。 瀏覽 Hacktoberfest issue

Derive the .cmi / .cmt / .ast magic numbers instead of bumping them in every PR

未關閉
  • 哪裡不對？
#8,947 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

還沒有人認領這個 Issue。

評估

難度
5/5
預估耗時
一週以上
新手友好度
35/100
Issue 類型
功能
描述清晰度
描述清楚
活躍度
活躍
技術堆疊
ocaml
領域
compilers

研究方向

Start with compiler/ext/config.ml and inspect how the .cmi, .cmt, and .ast magic numbers are defined, then trace the serialized interfaces and release tooling described in the proposal. The work spans digest generation, release recording and counter updates, and possibly dev build suffixes and prefix changes. Done means release counters change only when serialized layouts change, outside tools can distinguish compatible releases, and the changelog notes the prefix change.

由索引模型根據 Issue 內容生成。

描述

Problem

compiler/ext/config.ml holds hand-numbered magic numbers for .cmi (Caml1999I036), .cmt (Caml1999T043) and marshaled .ast files (ResImpl01315 / ResIntf01315). Every PR that changes a serialized type bumps them, so parallel PRs constantly conflict on the same lines. That's the same problem we had with CHANGELOG.md before fragments. There have been about 20 bumps since August.

The per-PR precision buys nothing:

  • Rebuilds after a compiler change are driven by bsc_hash, which both build systems store, not by the magic numbers.
  • Outside tools only ever see released versions, so intermediate bumps between two releases are invisible to them.
  • A bump forgotten in a PR fails silently: mixing files across a layout change crashes in Marshal instead of giving a clean error.

The Caml1999 prefix is a separate problem. OCaml 5.5 uses Caml1999I037 / Caml1999T037, so our I036 is most likely a real OCaml release's .cmi number, and the next bump would collide with OCaml 5.5. An OCaml tool would then accept a ReScript .cmi and misread it, instead of rejecting it.

What outside tools need

Tools that read .cmi/.cmt files may rely on the magic number. They need:

  • A stable number for each release.
  • A change between releases only when the format may have changed, so they can tell that two releases share a format.
  • Ordering, for "built by a newer compiler" checks (cmi_format.ml already uses it for its older/newer error).

Proposal

Bump the counters at release time, not in PRs:

  1. A dune rule computes a digest of the interfaces whose values are serialized. For .cmi that is types, path, ident, parsetree, …; for .cmt add typedtree; for .ast it is parsetree. Prefer whole directories or dune's cmi digests over a hand-picked file list, which would go stale like manual bumps do.
  2. A checked-in file records the counter and digest from the last release. PRs never touch it.
  3. The release script, or a CI check on release PRs, compares the current digest with the recorded one. If they differ, it bumps the counter and records the new digest. Comment-only edits cause harmless extra bumps.
  4. Optional: dev builds append the digest (e.g. …037+3fa9c1d2), so mixing two dev builds that share a counter but differ in layout gives a clean error instead of a crash. Releases ship the bare counter.
  5. Switch to our own prefixes (e.g. ResCmi… / ResCmt…, like the .ast numbers already did), so OCaml tools reject our files. Note this in the changelog because outside tools will see it.

Not in scope: .cmj has no magic number yet, only a digest of its own content (js_cmj_format.ml has a TODO). It could get a counter under the same scheme. The frozen Parsetree0 PPX numbers (Caml1999M022 / N022) must never change and stay as they are.

Alternatives considered

  • The compiler version as the magic number. Stable per release and never touched by PRs. However, it changes on every release even when the format didn't, it has no meaningful ordering across prereleases, and dev builds sharing a version can't detect a layout mismatch.
  • A pure content digest. Exact and never conflicts, but outside tools can't see that two releases share a format, and there's no ordering.
主要語言
OCaml
星號
7.5k
分支
483
平均合併
21 小時 8 分鐘
30 天內合併 PR
183

環境準備

在 Codespaces 中開啟

在瀏覽器裡用你自己的 GitHub 帳號啟動這個專案的開發容器。

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

rescript-lang/rescript 的其他 Issue

查看 rescript-lang/rescript 的全部 Issue

相似的 Issue

更多 Compilers Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。