Add a Foundational Principles section stating the model's governing why - #244
Merged
Conversation
The branch, release, and versioning rules were documented as mechanics without the unifying motivation that governs them. State it up front: pull-vs-push distribution grounds release restraint; dual-target branch sync is what makes the signed/linear/no-backport model possible; the 2-digit version carries human meaning while NBGV guarantees monotonic builds; contracts fix outcomes not implementations and favor reuse. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new "Foundational Principles" section to AGENTS.md to document the underlying rationale ("why") behind the repo's branching, release, and versioning mechanics so readers see the motivation before the detailed rules.
Changes:
- Introduces a top-level "Foundational Principles" section describing distribution semantics (pull vs push), dual-branch sync rationale, and the two-version-number model.
- Adds cross-references to existing sections (e.g., Branching Model, Release Model, WORKFLOW.md) rather than duplicating the full mechanics.
Acknowledge PUBLISH_ON_MERGE as an opt-in override to the two-phase default, and that a develop->main promotion is a clean forward merge by default (sync can be broken and restored). Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
HACS surfaces a pending update to installed users rather than auto-installing a release; say so accurately. Change 'break' to 'breaking change' for list parallelism. Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Match the 'No-op republish guarantee' wording used elsewhere in the file so the phrase greps cleanly. Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Align the Foundational Principles bullet with the 'main -> develop back-merges' / 'forward-only' terminology used in the Branching Model section. Addresses Copilot review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Merged
ptr727
added a commit
that referenced
this pull request
Jul 7, 2026
Two-phase promotion of the accumulated governance work on `develop` to `main`. Carries #244-#251: - #244 Foundational Principles (the model's governing *why*) - #245 Replace the mypy ban with a strong-typing policy - #246 aiopurpleair + homeassistant-purpleair audit reports - #247 Catalog the 14 backlog repos; add the `eda` type and `releaseTrigger: none` - #248 Branch-conditional Docker platforms (multi-arch main, amd64 elsewhere) - #249 Retire the both-branch matrix for symmetric single-branch self-release - #250 Declare workflow YAML as LF and validate line endings in CI - #251 Extend line-ending governance to pattern files and catalog snippets All commits were reviewed and CI-green on their individual develop PRs.
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.
Documents the governing motivation behind the branch, release, and versioning rules, which were previously captured only as mechanics.
Placed as a new top section in AGENTS.md so the why is read before the specific rules. References existing sections rather than restating them.