docs(solutions): capture two learnings from CPT path-only Breaks PR#108
Merged
Conversation
Two new best-practices docs distilled from halos-org/container-packaging-tools#203 (auto-inject Debian Breaks: on Homarr stack for routed visible apps), plus bidirectional cross-references in the pre-existing 2026-04-30 policy doc. 1. `2026-05-13-prefer-breaks-over-depends-for-partial-upgrade-gating.md` When the 2026-04-30 Skip-Depends-pins doc's Keep-the-pin conditions fire (silent failure mode OR manual partial upgrades are an expected operational pattern), the right Debian primitive is `Breaks: peer (<< X)`, not `Depends: peer (>= X)`. `Breaks` is conditional on the peer being installed — doesn't over-constrain devices that don't ship the peer at all. PR #203 is the worked example. 2. `2026-05-13-shared-predicate-over-parallel-if-chains.md` When two call sites must answer the same non-trivial question about the same input, extract that question into a named predicate consumed by every site. Maintainer-discipline comments like 'stay in lock-step' are not contracts; PR #203's pre-review state had drifted between the path-only-URL emission trigger in registry.py and the Breaks injection trigger in template_context.py. The fix extracted `registry.emits_path_only_url` as the shared source of truth. The 2026-04-30 policy doc gains 'Related' links to both new docs so a future PR author hitting the same question lands on whichever angle fits their context first.
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
1 participant
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 new best-practices docs distilled from halos-org/container-packaging-tools#203 (which adds conditional Debian
Breaks:auto-injection to CPT-generated .debs for routed visible web apps). Plus bidirectional cross-references in the pre-existing2026-04-30-skip-apt-depends-pins-sibling-halos-packages.mdpolicy doc.What's added
2026-05-13-prefer-breaks-over-depends-for-partial-upgrade-gating.mdCompanion to the 2026-04-30 Skip-Depends-pins policy. That doc names the Keep-the-pin conditions (silent failure mode, manual partial upgrades are an expected operational pattern) but doesn't recommend a Debian primitive. This doc says: when those conditions fire, use
Breaks: peer (<< X), notDepends: peer (>= X).Breaksis conditional on the peer being installed — it doesn't over-constrain devices that don't ship the peer at all. Includes the apt resolver behaviour matrix (BreaksvsDependsvsConflicts), a worked wrong/right example pulled from PR #203, and the generator-injection pattern.2026-05-13-shared-predicate-over-parallel-if-chains.mdGeneral code-organisation pattern surfaced during PR #203's CE review. When two call sites must answer the same non-trivial question about the same input, extract a named predicate. Maintainer-discipline comments like "keep this in sync with X" or "the two stay in lock-step" aren't contracts — they fail silently when one site evolves. PR #203's pre-review state had the path-only-emission trigger duplicated between
registry.pyandtemplate_context.pywith exactly such a comment. The fix extractedregistry.emits_path_only_urlas the shared source of truth. Doc covers when to apply (and when not to — caveats included).Cross-references in
2026-04-30-skip-apt-depends-pins-sibling-halos-packages.mdTwo new lines added to the Related section pointing forward to the new docs. Future PR authors hitting the partial-upgrade pin question will land on whichever angle fits their context first.
Cross-repo nature
Both learnings are cross-repo (Debian packaging hygiene + general code-organisation pattern), so they belong in the workspace, alongside the existing 2026-04-30 doc — not in any individual repo. The workspace
AGENTS.mdalready surfacesdocs/solutions/to agents, so discoverability is intact.