This page is the contributor policy for ceph_bug_<id> build tags: what a
tag's record must hold, when a difference deserves a tag, how a tag selects
its path, and how its identity is kept. The registered tags are listed in the
Bug compatibility guide,
which a unit test keeps in agreement with
bug-compatibility-tags.json.
| Field | Required content |
|---|---|
| Identity | Exact tag, bug ID, authoritative tracker link and affected operation. Unassigned-ID, namespace and retirement decisions must be explicit. |
| Defect evidence | Observed symptom, trigger and supporting evidence; distinguish confirmed observations from hypotheses. |
| Image boundaries | Confirmed affected/fixed versions with the image references that were run, the native build each reported (ceph --version) and the platform; list unverified boundaries separately. A release string alone is insufficient: the boundary is what the symptom and its prerequisites showed on the image that ran. |
| Behavior | Ordinary versus tag-enabled operation, preserved final success criteria, and why the alternate path may fail on fixed/unaffected images. |
| Selection | When to enable or omit it, including custom/partially patched images, valid build/test invocations and independently selected combinations. |
| Conflicts and scope | Incompatible tags and their diagnostics, plus limitations when one binary must operate on differently patched targets. |
| Verification | No-tag/tag/composition checks and evidence that the intended path was selected; compilation and native results reported separately. |
| Execution provenance | Active compatibility selection, source/build, the image references that ran, attempt and cleanup outcome. |
| Maintenance | Current support, unresolved limitations and any reviewed deprecation/retirement decision. |
Add entries only with their implementation and scoped validation. Do not list
an invented upstream ID or an unverified workaround as supported. A successful
build with an unused custom tag is not selection evidence. Planner tests use
synthetic ceph_bug_synthetic_* tags only in their own fixtures; those are not
registered.
| Difference | Approach |
|---|---|
| Feature availability | Prefer the relevant target's actual capabilities when they can be inspected. A missing feature remains unavailable. |
| Release syntax or representation | Adapt command forms/output as appropriate while preserving the supported operation. Do not turn every version branch into a bug tag. |
| Behavioral bug or fix | Use an explicitly selected bug-ID compatibility path with evidence for the defect and the ordinary/alternate behavior. |
This policy covers behavioral compatibility; security fixes are a separate consideration. The release/image guide continues to describe existing behavior and image requirements.
A reported release is not proof of a behavioral bug or fix. A custom image can contain a backport while reporting the same release as an affected official image. An image-tag suffix or an assumed patch-version ordering is not a standard declaration of its fixes. Published images are validated choices, not an allowlist excluding custom images that meet the image requirements. A feature probe may establish availability without distinguishing buggy and fixed behavior. Safe behavioral probes may supply evidence, but universal automatic detection is not a prerequisite for explicit selection.
- Use
ceph_bug_<id>as the naming template, with a documented bug identifier. The template is not a supported tag or a command to copy. - With no tag for a behavior, compile its ordinary implementation. A selected tag compiles only that bug's compatibility implementation. Use separately constrained source files with the same callable contract where appropriate.
- Keep independent bugs independently selectable and composable. One bug with the same compatibility behavior across releases keeps one identity; list affected releases in the catalogue instead of creating release-wide bundles.
- Do not override explicit build selection from a runtime release string or image name. Fixed custom builds use the ordinary path for the fixed bug, while selecting other bugs that still apply.
- The caller selects paths to match the actual image. An omitted required tag or an incompatible selection may fail. Do not convert that failure to a skip or silently try the opposite path until something passes.
| Actual target behavior | Selection for this bug | Intended path |
|---|---|---|
| Unaffected official or custom image | None | Ordinary |
| Affected image | Its registered bug tag | Compatibility |
| Custom image fixes A but retains independent B | B only | Ordinary for A, compatibility for B |
These rows define intended selection, not validated image combinations. A successful tagged run alone does not prove that its workaround was necessary.
Both paths must preserve the requested operation and final success criteria. An alternate sequence or result interpretation must not suppress failures, fabricate evidence, weaken byte/identity/cleanup assertions, or declare an unavailable feature supported. Changing the requested semantics needs an explicit design decision. Retain uncertain outcomes; do not replay a mutation to obtain a passing observation.
Tests must exercise the same contract in ordinary and compatibility builds.
Splitting files must not make the affected tests disappear under one selection.
Integration-suite selectors such as all and opt-in native_regression select
test coverage; they must not implicitly enable every bug workaround.
Build selection applies to the package implementation in the test binary, not one container, cluster or call. A binary cannot select two mutually exclusive implementations of the same behavior for different targets. A multicluster scenario that needs both simultaneously remains a design problem; separate executions do not prove that scenario, and this policy creates no runtime override API.
The following must be settled for an implementation, rather than inferred from this policy or filled with placeholder IDs:
- Authoritative tracker/identifier spelling, namespace collisions and bugs without assigned upstream IDs. Retirement and binding history are recorded in Identity binding and retirement.
- Explicit conflict declarations and diagnostics for incompatible selections; do not rely on duplicate-symbol errors or undocumented precedence.
- Selection verification beyond the planner. Go can accept unused or misspelled custom tags, so a successful build alone does not prove a path was selected. The planner refuses unregistered selections and requires each registered tag's sources to constrain on it; it does not prove that a compiled source behaves differently.
- Which callers may set a selection, and for which image cohorts.
tagged-runtime.ymltakes it as one input, history rows record it and job summaries show it beside the images the job ran, but no caller sets it yet. Every additional supported tag adds configurations to maintain.
A published ceph_bug_<id> spelling is bound to one defect for as long as the
repository is maintained. The catalogue must keep that binding from being
rewritten by a later edit, so reviewers and any future check need to know where
it lives and which edits change it.
- The canonical binding is the
tagandtrackerpair of that tag's entry inbug-compatibility-tags.json. The v1 entry permits exactlytag,tracker,statusandsources, and this policy adds no identity or alias field to it. The tag spelling is the key; the tracker is the one canonical link of the defect it names. - A retired tag keeps its entry as a tombstone, with
statusretiredand the sametagandtracker. Its spelling is never deleted or reassigned. - Alias history is not stored in the entry. A reviewed alias (for example a
moved or redirected tracker URL for the same defect) is recorded in that
tag's identity record under Registered tags, and the
edit history of both files on the maintained branch is the immutable ledger.
The prior link is added to the identity record in the same change that
replaces the entry's
tracker. - Published release tags are never edited to record any of this. A correction lands on the maintained branch and ships in a new version.
How the binding of an existing tag may change (link edits, retirement, reactivation) is decided with the first registered tag. Until then a retired entry is never deleted, its spelling never names another defect, and a retired tag is never made supported again.
- The single-snapshot validator (
bug_registry) requires the exact v1 fields, onehttpstracker string and no repeated spelling. It accepts two distinct tags with the same tracker URL, so it does not prove identity. - The registered-source check (
bug_registry_sources) and the retired-source guard refuse a retired tag that still guards a test. A valid retirement must also remove those source references. - The retired-source scan (
bug_retired_sources) refuses a retired tag in the//go:buildor// +buildheader of any maintained Go file and names each path.testdata,vendorand dot or underscore directories are outside its scope, and tag words in comments or string literals are not constraints. It runs in every planner command exceptmodules. - Selection refuses unregistered, retired, repeated and conflicting tags.
- Classify each release or capability branch as the
policy does. A release-syntax,
representation or detected-capability branch is ordinary code; only a branch
that needs a different path for an image with a behavioral defect, where that
path fails on a fixed image, becomes a registered
ceph_bug_<id>tag. - Register a concrete tag in the catalogue with its authoritative bug link, ordinary/alternate contract, confirmed image boundaries and selection advice. Do not invent an upstream issue number or register this naming template.
- Verify no-tag and individual-tag selection, independent combinations, clear conflict refusal and retained tests. Record compilation separately from native compatibility evidence.
- Retain native evidence for an affected image using the matching path and a fixed/unaffected image using the ordinary path. Exercise mismatched selections where reproducible and a partial-patch combination where applicable. Keep unverified combinations and same-binary mixed-target limits explicit.
- Identify the selected paths alongside source SHA, actual release/build, the image references that ran, platform and attempt/cleanup results. An image needs no registry digest to count (Image references). Preserve failed attempts; do not infer coverage from a later retry or an unrelated cohort.
- Review the catalogue, testing instructions, release implications and maintenance burden together. Published release tags remain immutable.
Use the existing testing workflow and release process.