Skip to content

Commit 1888450

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

File tree

3 files changed

+226
-0
lines changed

3 files changed

+226
-0
lines changed

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
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: Extract PR number and fetch changes
32+
33+
First, let me extract the PR number from the URL and get the list of changed files:
34+
35+
```bash
36+
# Extract PR number from URL
37+
PR_NUMBER=$(echo "$ARGUMENTS" | grep -oE '[0-9]+$')
38+
echo "🔍 Reviewing PR #$PR_NUMBER"
39+
40+
# Get changed Go files in API directories
41+
gh pr view "$PR_NUMBER" --json files --jq '.files[].path' | grep '\.go$' | grep -E '/(v1|v1alpha1|v1beta1)/'
42+
```
43+
44+
## Step 2: Run linting checks
45+
46+
```bash
47+
echo "⏳ Running linting checks..."
48+
make lint
49+
```
50+
51+
## Step 3: Documentation validation
52+
53+
For each changed API file, I'll validate:
54+
55+
1. **Field Documentation**: All struct fields must have documentation comments
56+
2. **Optional Field Behavior**: Optional fields must explain what happens when they are omitted
57+
3. **Validation Documentation**: Validation rules must be documented and match markers
58+
59+
Let me check each changed file for these requirements:
60+
61+
```thinking
62+
I need to analyze the changed files to:
63+
1. Find struct fields without documentation
64+
2. Find optional fields without behavior documentation
65+
3. Find validation annotations without corresponding documentation
66+
67+
For each Go file, I'll:
68+
- Look for struct field definitions
69+
- Check if they have preceding comment documentation
70+
- For optional fields (those with `+kubebuilder:validation:Optional` or `+optional`), verify behavior is explained
71+
- For fields with validation annotations, ensure the validation is documented
72+
```
73+
74+
## Step 4: Report results
75+
76+
I'll provide a comprehensive report showing:
77+
- ✅ Files that pass all checks
78+
- ❌ Files with documentation issues
79+
- 📋 Specific lines that need attention
80+
- 📚 Guidance on fixing any issues
81+
82+
The review will fail if any documentation requirements are not met for the changed files.

‎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)