Should source.json in Bazel module registries be immutable?

[volodymyr-shulga]

Hi Bazel team,

I’m implementing a custom Bazel registry (similar to the Bazel Central Registry) and noticed that each module version directory contains a source.json file, which defines the source URL, integrity hash, and optionally patches.

From my understanding of Bazel’s focus on hermetic and reproducible builds, once a module version is published, its content should not change. That would imply that source.json is effectively immutable after publication.

However, I couldn’t find explicit documentation stating whether source.json is required to remain unchanged, or if it is acceptable to update it (e.g., to add or change patches) for the same module version.

My questions:
1. Is there an official policy or recommendation that source.json must be immutable once published?
2. If it is allowed to change, what are the implications for Bazel clients (e.g., caching, reproducibility, integrity hash checks)?
3. For private registries, is it acceptable to treat source.json as mutable, or is the recommendation still to publish a new module version instead?

If there’s existing documentation or guidelines that cover this, I’d appreciate a link.

Thanks!

[meteorcloudy]

Yes, this is the https://github.com/bazelbuild/bazel-central-registry/blob/main/docs/README.md#add-only policy, and has been enforced by the bcr presubmit: https://github.com/bazelbuild/continuous-integration/blob/c248c025949d1a3a2773b9d45346938598fdd39c/buildkite/bazel-central-registry/bcr_presubmit.py#L344-L350

[volodymyr-shulga]

Thank you, that makes perfect sense