NO-JIRA: Add CLAUDE.md by sanchezl · Pull Request #333 · openshift/service-ca-operator

sanchezl · 2026-03-18T23:29:31Z

Add CLAUDE.md with development and architecture guidelines.

coderabbitai · 2026-03-18T23:29:47Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1cf297f4-7d65-48a5-b8dc-dd84afb92e8a

📥 Commits

Reviewing files that changed from the base of the PR and between a1d3e49 and 29a2440.

📒 Files selected for processing (1)

CLAUDE.md

Walkthrough

Adds a new repository documentation file CLAUDE.md describing build/test commands, operator architecture, controller responsibilities, annotation contracts, key constants/namespaces, and testing/code-style guidance. No functional code changes.

Changes

Cohort / File(s)	Summary
Documentation `CLAUDE.md`	New repository documentation detailing build & test commands (`make build`, `make test-unit`, `make test-e2e`, `make update-bindata`, `make verify-bindata`), two-process operator architecture and responsibilities (single `service-ca-operator` binary with operator and controller processes), user-facing annotation contracts (current and legacy `service.alpha...` keys and "vulnerable legacy injection" behavior), key namespaces and constants locations, PR/commit conventions, and testing/style guidance (unit tests in `pkg/`, e2e in `test/e2e/`, use of `openshift/library-go`).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can generate a title for your PR based on the changes.

Add @coderabbitai placeholder anywhere in the title of your PR and CodeRabbit will replace it with a title based on the changes in the PR. You can change the placeholder by changing the reviews.auto_title_placeholder setting.

openshift-ci-robot · 2026-03-18T23:30:01Z

@sanchezl: This pull request explicitly references no jira issue.

Details

In response to this:

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

wangke19

Review Summary

Thanks for adding CLAUDE.md — the architecture section is excellent and the two-process / three-controller breakdown will be very helpful for AI-assisted development. A few issues to address:

🔴 Blocking: `make update-deps-gomod` does not exist

The target make update-deps-gomod is not defined in this project's Makefile or the vendored build-machinery-go. Running it produces:

make: *** No rule to make target 'update-deps-gomod'.  Stop.

The available dependency-related make targets are verify-deps and update-deps-overrides. The correct way to update vendored dependencies is:

go mod tidy && go mod vendor

Please fix this before merging.

🟡 Missing: PR / Commit Conventions (Two-Commit Rule)

This project follows a two-commit PR structure (consistent with other OpenShift operators). Without this guidance, an AI assistant will commit source code, go.mod, go.sum, vendor/, and generated bindata.go all in one commit. Suggest adding a new section:

## PR / Commit Conventions

All PRs must contain exactly 2 commits:

**Commit 1 — code changes only**
Source code changes only. Exclude `go.mod`, `go.sum`, `vendor/`, and all generated files.

**Commit 2 — generated artifacts and dependencies**
All files produced by `make update` or dependency updates:
- `go.mod` and `go.sum`
- `vendor/` (kept in sync via `go mod tidy && go mod vendor`)
- `pkg/operator/v4_00_assets/bindata.go` (produced by `make update-bindata` when `bindata/v4.0.0/` changes)

Always base commits on `upstream/main`, not `origin/main`.

Before pushing, verify:
\`\`\`bash
git log --oneline upstream/main..HEAD    # must show exactly 2 commits
git diff upstream/main..HEAD --name-only # confirm files land in the right commit
\`\`\`

🟡 Missing: `make verify` in Commands

make verify runs verify-gofmt, verify-govet, and verify-generated — the standard pre-submit check. Worth adding to the Commands section so an AI knows to run it before declaring work done.

🟡 Missing: Where to add new e2e tests

The test/e2e/ directory contains both e2e.go (OTE path, active) and e2e_test.go (legacy, being phased out). Without guidance, an AI would likely add tests to the wrong file. Suggest adding to ## Testing:

New e2e tests must be added to test/e2e/e2e.go (OTE format), not test/e2e/e2e_test.go (legacy — being phased out).

🟡 Minor: `bindata.go` not identified as generated

The doc says to run make update-bindata after modifying bindata/v4.0.0/, but doesn't name the output file (pkg/operator/v4_00_assets/bindata.go). Calling it out explicitly helps an AI know never to hand-edit it and to commit it in Commit 2, not Commit 1.

ℹ️ Nit: Redundant top-level header

The # CLAUDE.md H1 heading is just the filename — consider dropping it or replacing with something descriptive like # Service CA Operator — AI Assistant Guidelines.

wangke19 · 2026-03-20T13:02:52Z

+
+# Update all generated files
+make update
+


make update-deps-gomod does not exist in this project. The build-machinery-go vendored copy and the project Makefile only define verify-deps and update-deps-overrides. Running this will immediately fail with No rule to make target.

Please replace with:

# Update vendored dependencies go mod tidy && go mod vendor

Thanks for the review. Done.

wangke19 · 2026-03-20T16:40:07Z

/lgtm

openshift-ci · 2026-03-20T16:41:12Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: sanchezl, wangke19
Once this PR has been reviewed and has the lgtm label, please assign bertinatto for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

openshift-ci · 2026-03-20T19:36:12Z

@sanchezl: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

wangke19 · 2026-03-23T08:21:20Z

/verified by CI

openshift-ci-robot · 2026-03-23T08:22:57Z

@wangke19: Jira verification commands are restricted to collaborators for this repo.

Details

In response to this:

/verified by CI

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

wangke19 · 2026-03-25T03:10:37Z

/verified by @wangke19

openshift-ci-robot · 2026-03-25T03:10:48Z

@wangke19: This PR has been marked as verified by @wangke19.

Details

In response to this:

/verified by @wangke19

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

wangke19 · 2026-03-25T03:11:21Z

/cc @bertinatto

Add AI assistant guidelines to help AI coding tools (Claude Code, Cursor, Copilot, etc.) understand project structure and workflows. Key sections: - Build & test commands (make targets, OTE framework) - OAuth resources (OAuthAccessToken, OAuthAuthorizeToken, User/Identity) - Token validation architecture - Code generation workflow (make update/verify) - Two-commit PR convention - Testing strategy (unit, E2E with OTE) CLAUDE.md symlinked to AGENTS.md for backwards compatibility. Reference: openshift/service-ca-operator#333

CLAUDE.md was added in PR openshift#333 as a standalone file. PR openshift#362 later added AGENTS.md (with the same content restructured) plus ARCHITECTURE.md and CONTRIBUTING.md, which together cover everything in the original CLAUDE.md. Replace the standalone file with a symlink so Claude Code discovers the same content as other AI tools reading AGENTS.md — one source of truth, zero duplication.

sanchezl changed the title ~~Add CLAUDE.md with development and architecture guidelines~~ NO-JIRA: Add CLAUDE.md Mar 18, 2026

openshift-ci Bot requested review from bertinatto and p0lyn0mial March 18, 2026 23:29

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Mar 18, 2026

wangke19 reviewed Mar 20, 2026

View reviewed changes

Add CLAUDE.md with development and architecture guidelines

29a2440

sanchezl force-pushed the add-claude.md branch from a1d3e49 to 29a2440 Compare March 20, 2026 16:27

openshift-ci Bot assigned wangke19 Mar 20, 2026

openshift-ci Bot added the lgtm Indicates that a PR is ready to be merged. label Mar 20, 2026

openshift-ci-robot added the verified Signifies that the PR passed pre-merge verification criteria label Mar 25, 2026

openshift-merge-bot Bot merged commit 3b5a3ca into openshift:main Mar 25, 2026
12 checks passed

wangke19 mentioned this pull request Apr 1, 2026

Add AGENTS.md for AI agent guidance openshift/cluster-kube-apiserver-operator#2077

Closed

4 tasks

wangke19 mentioned this pull request Apr 3, 2026

docs: add AGENTS.md for AI-assisted development openshift/oauth-apiserver#188

Open

sanchezl mentioned this pull request Jul 6, 2026

CNTRLPLANE-3718: Replace standalone CLAUDE.md with symlink to AGENTS.md #363

Open

3 tasks

Uh oh!

Conversation

sanchezl commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

openshift-ci-robot commented Mar 18, 2026

Uh oh!

wangke19 left a comment

Choose a reason for hiding this comment

Review Summary

🔴 Blocking: make update-deps-gomod does not exist

🟡 Missing: PR / Commit Conventions (Two-Commit Rule)

🟡 Missing: make verify in Commands

🟡 Missing: Where to add new e2e tests

🟡 Minor: bindata.go not identified as generated

ℹ️ Nit: Redundant top-level header

Uh oh!

wangke19 Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

sanchezl Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

wangke19 commented Mar 20, 2026

Uh oh!

openshift-ci Bot commented Mar 20, 2026

Uh oh!

openshift-ci Bot commented Mar 20, 2026

Uh oh!

wangke19 commented Mar 23, 2026

Uh oh!

openshift-ci-robot commented Mar 23, 2026

Uh oh!

wangke19 commented Mar 25, 2026

Uh oh!

openshift-ci-robot commented Mar 25, 2026

Uh oh!

wangke19 commented Mar 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sanchezl commented Mar 18, 2026 •

edited

Loading

coderabbitai Bot commented Mar 18, 2026 •

edited

Loading

🔴 Blocking: `make update-deps-gomod` does not exist

🟡 Missing: `make verify` in Commands

🟡 Minor: `bindata.go` not identified as generated