openshift / openshift/ocm-agent-operator
Add CRD API backward compatibility constraint to CLAUDE.md
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 3
- Forks
- 59
- Avg merge
- 10h 17m
- Merged PRs (30d)
- 25
Description
What happened
The code agent on PR #356 renamed JSON serialization tags from resendWait to resendInterval on FleetNotification.ResendWait and NotificationRecordByName.ResendWait CRD types (commit d6366cb). This was a backward-incompatible CRD schema change — existing custom resources stored in etcd would fail validation, and FiringCanBeSent would zero-default, causing notification spam. The review agent (run 33465133921) correctly caught this as 2 critical findings and the fix agent reverted the change, but the initial error cost ~$8.54 in review + fix compute and ~32 minutes of wall-clock time.
What could go better
CLAUDE.md has constraints about generated files ("Never edit deploy/crds/*.yaml") and architectural boundaries ("API Types are pure data structures"), but nothing about CRD API backward compatibility. The code agent had no guidance that renaming JSON/YAML serialization tags on existing CRD types is a breaking change that requires a conversion webhook or migration strategy. With an explicit constraint, the code agent would have avoided the rename entirely and the review+fix cycle would not have been needed. Confidence: high — the agent's commit message shows it believed the rename was a straightforward fix, not a breaking change.
Proposed change
Add a CRD backward compatibility constraint to the Agents MUST section of CLAUDE.md, in the "Repo-Specific Constraints" or "Architectural Boundaries" area:
### CRD API Stability
- **Never rename JSON/YAML serialization tags** on existing CRD types (`api/v1alpha1/`) — this is a backward-incompatible schema change that breaks existing custom resources stored in etcd
- **Never remove or rename required fields** from CRD specs or status types
- If a field rename is genuinely needed, it requires a conversion webhook or explicit documentation that no existing resources use the old schema
- When in doubt, preserve the existing JSON tag and add a comment explaining the naming discrepancy
Validation criteria
The next 3 code agent runs on this repo that touch api/v1alpha1/ types should not attempt JSON tag renames or backward-incompatible CRD schema changes without proposing a migration strategy. If a Jira issue requests a field rename, the code agent should preserve backward compatibility and explain the constraint in its PR description.
Generated by retro agent from https://github.com/openshift/ocm-agent-operator/pull/357
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open CLAUDE.md and read the Agents MUST section, especially the existing generated-file and architectural-boundary constraints. Add the proposed CRD API Stability guidance in the Repo-Specific Constraints or Architectural Boundaries area, preserving the listed backward-compatibility requirements.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 92/100