Repository navigation
Never author a node's Version — and always merge main before you push - #867
Merged
Merged
Conversation
Two rules from one day of chasing symptoms. MeshNodeVersioning.md: a `version` committed into a source file forks the install on any fresh mesh. MeshNode.Version is the OWNER's persistence clock — [Editable(false)], minted as current+1 — so a checked-in counter is a snapshot of some other mesh's clock. The store correctly refuses the backward write, the install fails, the partition has no readable root, every subscribe is denied (799 in one observed run), its NodeTypes never compile, and CI reports "Store/Plugin never reached compilationStatus Ok" — a compile error five minutes and four causal steps from the actual failure. Found in every node repo: 13 modules, counters as high as 4489. The authored version is SemVer and only SemVer. Includes the explicit warning not to "fix" a fork by relaxing the guard, which the guard's own message already says. AGENTS.md: sync with main before every push and PR, and again before merging if main has moved. Now enforced by the ruleset (strict_required_status_checks_policy), because the cost was invisible and large — a stale branch re-samples flakes main has ALREADY fixed, and every one looks like a defect in your change. #794 burned five CI runs and most of a day that way: three different red tests, two already fixed on main, none caused by the branch. The actionable form: if CI fails on something your diff does not touch, merge main BEFORE investigating anything. DocumentationLinkIntegrityTest green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HXtvWpB51YDAT5a3u1A81m
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation-only update capturing two operational rules that prevent expensive, hard-to-diagnose failures during module install/bootstrapping and CI validation.
Changes:
- Added a new “Never author
Versionin a source file” section to clarify thatMeshNode.Versionis an owner-minted persistence counter (not an authored SemVer) and why committing it forks fresh installs. - Strengthened
AGENTS.mdguidance to explicitly require syncing withmainbefore every push/PR, noting this is now enforced by GitHub ruleset policy.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/MeshWeaver.Documentation/Data/Architecture/MeshNodeVersioning.md | Documents the “don’t commit Version” rule with rationale, failure signature, and SemVer guidance. |
| AGENTS.md | Makes “merge main before push/PR” explicit and adds context on ruleset enforcement and why it matters. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
rbuergi
enabled auto-merge
August 6, 2026 19:29
auto-merge was automatically disabled
August 6, 2026 19:37
Pull request was closed
rbuergi
enabled auto-merge
August 6, 2026 19:39
Contributor
Contributor
Contributor
Contributor
Contributor
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two rules, both learned the expensive way today.
1.
MeshNodeVersioning.md— never authorVersionA
versioncommitted into a source file forks the install on any fresh mesh.MeshNode.Versionis the OWNER's persistence clock —[Editable(false)], minted ascurrent + 1— so a checked-in counter is a snapshot of some other mesh's clock:The symptom names the wrong thing — a compile error, five minutes and four causal steps from the real failure. It reads as a flaky compile for as long as you let it.
Found in every node repo: 13 modules, counters as high as 4489. The authored version is SemVer and only SemVer.
Also records the warning not to "fix" a fork by relaxing the guard — which the guard's own message already says: "Find the writer that adopted a stale own-node snapshot; do not relax this guard." The writer was a checked-in file.
Verified by reproduction: bootstrap failed twice, counters stripped, bootstrap passed — locally and on CI, where
Store/Plugin compilednow lands at +123s instead of timing out at 300s.2.
AGENTS.md— merge main before every push and PRNow enforced by the ruleset (
strict_required_status_checks_policy), so GitHub refuses a branch that is behind main.The rule exists because the cost is invisible and large: a stale branch re-samples flakes that main has already fixed, and every one looks like a defect in your change. #794 burned five CI runs and most of a day that way — three different red tests, two already fixed on main, none caused by the branch.
The actionable form: if CI fails on something your diff does not touch, merge main before investigating anything.
DocumentationLinkIntegrityTestgreen.🤖 Generated with Claude Code