Skip to content

Commit edc45f3

Browse files
JoelSpeedJoelSpeed
committed
Add initial AI api-review configuration
1 parent 588d549 commit edc45f3

File tree

3 files changed

+267
-0
lines changed

3 files changed

+267
-0
lines changed

‎.claude/commands/api-review.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: api-review
3+
description: Run strict OpenShift API review workflow for PR changes
4+
parameters:
5+
- name: pr_url
6+
description: GitHub PR URL to review
7+
required: true
8+
---
9+
10+
# Output Format Requirements
11+
You MUST use this EXACT format for ALL review feedback:
12+
13+
14+
+LineNumber: Brief description
15+
**Current (problematic) code:**
16+
```go
17+
[exact code from the PR diff]
18+
```
19+
20+
**Suggested change:**
21+
```diff
22+
- [old code line]
23+
+ [new code line]
24+
```
25+
26+
**Explanation:** [Why this change is needed]
27+
28+
29+
I'll run a comprehensive API review for the OpenShift API changes in the specified GitHub PR.
30+
31+
## Step 1: Pre-flight checks and branch management
32+
33+
First, I'll check for uncommitted changes and save the current branch:
34+
35+
```bash
36+
# Save current branch
37+
CURRENT_BRANCH=$(git branch --show-current)
38+
echo "📍 Current branch: $CURRENT_BRANCH"
39+
40+
# Check for uncommitted changes
41+
if ! git diff --quiet || ! git diff --cached --quiet; then
42+
echo "❌ ERROR: Uncommitted changes detected. Cannot proceed with API review."
43+
echo "Please commit or stash your changes before running the API review."
44+
git status --porcelain
45+
exit 1
46+
fi
47+
48+
echo "✅ No uncommitted changes detected. Safe to proceed."
49+
```
50+
51+
## Step 2: Extract PR number and checkout PR
52+
53+
```bash
54+
# Extract PR number from URL
55+
PR_NUMBER=$(echo "$ARGUMENTS" | grep -oE '[0-9]+$')
56+
echo "🔍 Reviewing PR #$PR_NUMBER"
57+
58+
# Checkout the PR
59+
echo "🔄 Checking out PR #$PR_NUMBER..."
60+
gh pr checkout "$PR_NUMBER"
61+
62+
# Get changed Go files in API directories
63+
echo "📁 Analyzing changed files..."
64+
gh pr view "$PR_NUMBER" --json files --jq '.files[].path' | grep '\.go$' | grep -E '/(v1|v1alpha1|v1beta1)/'
65+
```
66+
67+
## Step 3: Run linting checks on PR changes
68+
69+
```bash
70+
echo "⏳ Running linting checks on PR changes..."
71+
make lint
72+
```
73+
74+
## Step 4: Documentation validation
75+
76+
For each changed API file, I'll validate:
77+
78+
1. **Field Documentation**: All struct fields must have documentation comments
79+
2. **Optional Field Behavior**: Optional fields must explain what happens when they are omitted
80+
3. **Validation Documentation**: Validation rules must be documented and match markers
81+
82+
Let me check each changed file for these requirements:
83+
84+
```thinking
85+
I need to analyze the changed files to:
86+
1. Find struct fields without documentation
87+
2. Find optional fields without behavior documentation
88+
3. Find validation annotations without corresponding documentation
89+
90+
For each Go file, I'll:
91+
- Look for struct field definitions
92+
- Check if they have preceding comment documentation
93+
- For optional fields (those with `+kubebuilder:validation:Optional` or `+optional`), verify behavior is explained
94+
- For fields with validation annotations, ensure the validation is documented
95+
```
96+
97+
## Step 5: Generate comprehensive review report
98+
99+
I'll provide a comprehensive report showing:
100+
- ✅ Files that pass all checks
101+
- ❌ Files with documentation issues
102+
- 📋 Specific lines that need attention
103+
- 📚 Guidance on fixing any issues
104+
105+
The review will fail if any documentation requirements are not met for the changed files.
106+
107+
## Step 6: Switch back to original branch
108+
109+
After completing the review, I'll switch back to the original branch:
110+
111+
```bash
112+
echo "🔄 Switching back to original branch: $CURRENT_BRANCH"
113+
git checkout "$CURRENT_BRANCH"
114+
echo "✅ API review complete. Back on branch: $(git branch --show-current)"
115+
```
116+
117+
**CRITICAL WORKFLOW REQUIREMENTS:**
118+
1. MUST check for uncommitted changes before starting
119+
2. MUST abort if uncommitted changes are detected
120+
3. MUST save current branch name before switching
121+
4. MUST checkout the PR before running `make lint`
122+
5. MUST switch back to original branch when complete
123+
6. If any step fails, MUST attempt to switch back to original branch before exiting

‎AGENTS.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
This file provides guidance to AI agents when working with code in this repository.
2+
3+
This is the OpenShift API repository - the canonical location of OpenShift API type definitions and serialization code. It contains:
4+
5+
- API type definitions for OpenShift-specific resources (Custom Resource Definitions)
6+
- FeatureGate management system for controlling API availability across cluster profiles
7+
- Generated CRD manifests and validation schemas
8+
- Integration test suite for API validation
9+
10+
## Key Architecture Components
11+
12+
### FeatureGate System
13+
The FeatureGate system (`features/features.go`) controls API availability across different cluster profiles (Hypershift, SelfManaged) and feature sets (Default, TechPreview, DevPreview). Each API feature is gated behind a FeatureGate that can be enabled/disabled per cluster profile and feature set.
14+
15+
### API Structure
16+
APIs are organized by group and version (e.g., `route/v1`, `config/v1`). Each API group contains:
17+
- `types.go` - Go type definitions
18+
- `zz_generated.*` files - Generated code (deepcopy, CRDs, etc.)
19+
- `tests/` directories - Integration test definitions
20+
- CRD manifest files
21+
22+
## Common Development Commands
23+
24+
### Building
25+
```bash
26+
make build # Build render and write-available-featuresets binaries
27+
make clean # Clean build artifacts
28+
```
29+
30+
### Code Generation
31+
```bash
32+
make update # Alias for update-codegen-crds
33+
```
34+
35+
### Testing
36+
```bash
37+
make test-unit # Run unit tests
38+
make integration # Run integration tests (in tests/ directory)
39+
go test -v ./... # Run tests for specific packages
40+
```
41+
42+
### Validation and Verification
43+
```bash
44+
make verify # Run all verification checks
45+
make verify-scripts # Verify generated code is up to date
46+
make verify-codegen-crds # Verify CRD generation is current
47+
make lint # Run golangci-lint (only on changes from master)
48+
make lint-fix # Auto-fix linting issues where possible
49+
```
50+
51+
## Adding New APIs
52+
53+
All APIs should start as tech preview.
54+
New fields on stable APIs should be introduced behind a feature gate `+openshift:enable:FeatureGate=MyFeatureGate`.
55+
56+
57+
### For New Stable APIs (v1)
58+
1. Create the API type with proper kubebuilder annotations
59+
2. Include required markers like `+openshift:compatibility-gen:level=1`
60+
3. Add validation tests in `<group>/<version>/tests/<crd-name>/`
61+
4. Run `make update-codegen-crds` to generate CRDs
62+
63+
### For New TechPreview APIs (v1alpha1)
64+
1. First add a FeatureGate in `features/features.go`
65+
2. Create the API type with `+openshift:enable:FeatureGate=MyFeatureGate`
66+
3. Add corresponding test files
67+
4. Run generation commands
68+
69+
### Adding FeatureGates
70+
Add to `features/features.go` using the builder pattern:
71+
```go
72+
FeatureGateMyFeatureName = newFeatureGate("MyFeatureName").
73+
reportProblemsToJiraComponent("my-jira-component").
74+
contactPerson("my-team-lead").
75+
productScope(ocpSpecific).
76+
enableIn(configv1.TechPreviewNoUpgrade).
77+
mustRegister()
78+
```
79+
80+
## Testing Framework
81+
82+
The repository includes a comprehensive integration test suite in `tests/`. Test suites are defined in `*.testsuite.yaml` files alongside API definitions and support:
83+
- `onCreate` tests for validation during resource creation
84+
- `onUpdate` tests for update-specific validations and immutability
85+
- Status subresource testing
86+
- Validation ratcheting tests using `initialCRDPatches`
87+
88+
Use `tests/hack/gen-minimal-test.sh $FOLDER $VERSION` to generate test suite templates.
89+
90+
## Container-based Development
91+
```bash
92+
make verify-with-container # Run verification in container
93+
make generate-with-container # Run code generation in container
94+
```
95+
96+
Uses `podman` by default, set `RUNTIME=docker` or `USE_DOCKER=1` to use Docker instead.
97+
98+
## Custom Claude Code Commands
99+
100+
### API Review
101+
```
102+
/api-review <pr-url>
103+
```
104+
Runs comprehensive API review for OpenShift API changes in a GitHub PR:
105+
- Executes `make lint` to check for kube-api-linter issues
106+
- Validates that all API fields are properly documented
107+
- Ensures optional fields explain behavior when not present
108+
- Confirms validation rules and kubebuilder markers are documented in field comments
109+
110+
#### Documentation Requirements
111+
All kubebuilder validation markers must be documented in the field's comment. For example:
112+
113+
**Good:**
114+
```go
115+
// internalDNSRecords is an optional field that determines whether we deploy
116+
// with internal records enabled for api, api-int, and ingress.
117+
// Valid values are "Enabled" and "Disabled".
118+
// When set to Enabled, in cluster DNS resolution will be enabled for the api, api-int, and ingress endpoints.
119+
// When set to Disabled, in cluster DNS resolution will be disabled and an external DNS solution must be provided for these endpoints.
120+
// +optional
121+
// +kubebuilder:validation:Enum=Enabled;Disabled
122+
InternalDNSRecords InternalDNSRecordsType `json:"internalDNSRecords"`
123+
```
124+
125+
**Bad:**
126+
```go
127+
// internalDNSRecords determines whether we deploy with internal records enabled for
128+
// api, api-int, and ingress.
129+
// +optional // ❌ Optional nature not documented in comment
130+
// +kubebuilder:validation:Enum=Enabled;Disabled // ❌ Valid values not documented
131+
InternalDNSRecords InternalDNSRecordsType `json:"internalDNSRecords"`
132+
```
133+
134+
The comment must explicitly state:
135+
- When a field is optional (for `+kubebuilder:validation:Optional` or `+optional`)
136+
- Valid enum values (for `+kubebuilder:validation:Enum`)
137+
- Validation constraints (for min/max, patterns, etc.)
138+
- Default behavior when field is omitted
139+
- Any interactions with other fields, commonly implemented with `+kubebuilder:validation:XValidation`
140+
141+
**CRITICAL**: When API documentation states field relationships or constraints (e.g., "cannot be used together with field X", "mutually exclusive with field Y"), these relationships MUST be enforced with appropriate validation rules. Use `+kubebuilder:validation:XValidation` with CEL expressions for cross-field constraints. Documentation without enforcement is insufficient and will fail review.
142+
143+
Example: `/api-review https://github.com/openshift/api/pull/1234`

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)