diff --git a/.claude/commands/find-stakeholders.md b/.claude/commands/find-stakeholders.md new file mode 100644 index 0000000000..1bcd3d18cd --- /dev/null +++ b/.claude/commands/find-stakeholders.md @@ -0,0 +1,111 @@ +--- +description: Find potential stakeholder reviewers for an OpenShift enhancement proposal +--- + +You are helping to identify potential stakeholders who should review a new OpenShift enhancement proposal. + +## Your Task + +1. **Locate and read the enhancement proposal:** + - Ask the user which enhancement file they want to find stakeholders for (if not obvious from context) + - Read the entire enhancement proposal to understand: + - What the enhancement does (Summary, Motivation sections) + - Which domains/components it affects (look for references to operators, APIs, subsystems) + - Whether it involves API changes (API Extensions section, api-approvers field) + - Specific technologies mentioned (networking, storage, authentication, etcd, etc.) + - Any existing reviewers/approvers already listed in the YAML frontmatter + +2. **Identify the affected OpenShift components and repositories** based on what you learned from reading the enhancement: + - Look for references to specific operators (e.g., cluster-authentication-operator, console-operator, machine-config-operator) + - Look for references to core components (e.g., openshift/api, hypershift, installer, oauth-server) + - Look for references to domain-specific components (e.g., cluster-monitoring-operator, cluster-network-operator, cluster-ingress-operator) + - Create a list of potential repository names to search for + +3. **Query the openshift GitHub organization** to find the actual repository names: + - Use WebFetch to query the GitHub API for openshift repositories: `https://api.github.com/orgs/openshift/repos?per_page=100&page=1` + - Note: The API returns paginated results (100 per page). You may need to fetch multiple pages if needed. + - Search through the repository list to find repositories that match the components mentioned in the enhancement + - Look for repositories containing relevant keywords (e.g., if enhancement mentions "authentication", look for repos with "authentication" or "oauth" in the name) + - Common repository patterns (but don't rely solely on these): + - `-operator` (e.g., console-operator, machine-config-operator) + - `cluster--operator` (e.g., cluster-authentication-operator, cluster-network-operator) + - Component names without "-operator" suffix (e.g., installer, hypershift, api) + +4. **Fetch OWNERS files from the identified repositories** to get current maintainers: + - Use WebFetch to retrieve OWNERS files from the matched repositories + - Try both `master` and `main` branches: + - `https://raw.githubusercontent.com/openshift//master/OWNERS` + - `https://raw.githubusercontent.com/openshift//main/OWNERS` + - Fetch multiple repository OWNERS files in parallel when the enhancement affects multiple components + - Extract the `approvers` and `reviewers` lists from each OWNERS file + +5. **Use local enhancement OWNERS files as supplementary context** (lower priority): + - Look in `enhancements//OWNERS` files for related domains (if they exist) + - Available domains include: network, ingress, storage, installer, authentication, machine-config, kube-apiserver, etcd, monitoring, observability, cluster-logging, dns, security, and many others + - Check the root `OWNERS` file for staff engineers who handle broad-scope enhancements + - **Important:** Local enhancement OWNERS files may be outdated or missing. Always prioritize repository OWNERS files from step 4 over enhancement OWNERS files + +6. **Verify API reviewer assignment** (critical step): + - Check if the enhancement involves API changes (new APIs, API extensions, CRDs, webhooks, etc.) + - If it does, verify that the `api-approvers` field in the YAML frontmatter is populated + - Use WebFetch to retrieve the openshift/api OWNERS file: https://github.com/openshift/api/blob/master/OWNERS + - Verify that at least one person listed in the enhancement's `api-approvers` field appears in the openshift/api OWNERS file as an approver or reviewer + - If there is NO api-approver listed OR the listed api-approver is not in the openshift/api OWNERS file, recommend that the author reach out to the #forum-api-review Slack channel to request an API reviewer be assigned + - Slack channel link: https://redhat.enterprise.slack.com/archives/CE4L0F143 + +7. **Present your findings** in this format: + + ``` + ## Potential Stakeholder Reviewers for [Enhancement Name] + + ### Primary Repository: openshift/[repo-name] + **Approvers:** + - @username1 + - @username2 + + **Reviewers:** + - @username3 + - @username4 + + ### Related Repository: openshift/[related-repo-name] + **Approvers:** + - @username5 + + **Reviewers:** + - @username6 + + ### API Review Status + + [Either:] + ✅ **Good news!** The enhancement has @username listed as api-approver, who is confirmed as an [approver/reviewer] in the openshift/api OWNERS file. + + [Or:] + ⚠️ **Action needed:** This enhancement introduces API changes but [does not have an api-approver listed / has @username listed who is not in the openshift/api OWNERS file]. Please reach out to the #forum-api-review Slack channel (https://redhat.enterprise.slack.com/archives/CE4L0F143) to request an API reviewer be assigned. + + ### Recommended Next Steps: + 1. For the primary repository (openshift/[repo]), consider reaching out to [specific approver] as your enhancement approver + 2. Include reviewers from [list repositories] to ensure all affected areas are covered + 3. If this is a broad-scope enhancement affecting multiple pillars, consider consulting with staff engineers from the root OWNERS file + ``` + +8. **Provide guidance** on: + - Which approver would be most appropriate (remind them that a single approver is preferred) + - Which reviewers to include and what domain expertise they should focus on + - Whether they should reach out in `#forum-arch` on Slack if this is high-priority or broad-scope + +## Important Context + +- Enhancement reviewers should include representatives from any team that will need to do work for the enhancement +- The approver helps recognize when consensus is reached and doesn't need to be a subject-matter expert (but it helps) +- For broad-scope enhancements (changing OpenShift definition, adding required dependencies, changing customer support), a staff engineer approver is appropriate +- Clearly indicate what aspect of the enhancement each reviewer should focus on (see guidelines/README.md for examples) + +## Tool Usage + +- Use WebFetch to query the GitHub API for openshift organization repositories +- Use WebFetch to retrieve OWNERS files from identified openshift repositories (primary source of truth) +- Use WebFetch to retrieve the openshift/api OWNERS file for API reviewer verification +- Use the Glob tool to find local enhancement OWNERS files: `find enhancements -name "OWNERS"` (supplementary context only) +- Use the Read tool to read local enhancement OWNERS files if needed (supplementary context only) +- Be efficient: fetch multiple OWNERS files in parallel when possible +- Remember: Repository OWNERS files are the authoritative source and should take priority over local enhancement OWNERS files diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..6ca2fcd41d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,178 @@ +# AGENTS.md + +This file provides guidance to AI agents when working with code in this repository. + +## Repository Overview + +This is the OpenShift Enhancement Proposals repository, inspired by the Kubernetes enhancement process. It provides a centralized place to propose, discuss, and document enhancements to OpenShift (both OKD and OCP). Enhancements are tracked as markdown documents with YAML frontmatter metadata. + +## Repository Structure + +- `enhancements/` - Enhancement proposals organized by domain (e.g., `network/`, `installer/`, `machine-config/`, `authentication/`, etc.) +- `guidelines/` - Process documentation including the enhancement template +- `dev-guide/` - Developer guides for various OpenShift subsystems +- `tools/` - Go-based CLI tools for managing enhancements +- `this-week/` - Weekly and annual enhancement summary reports +- `hack/` - Shell scripts for linting and automation + +## Common Commands + +### Linting +```bash +# Build the linter container image +make image + +# Run markdown linter on changed files +make lint + +# Override the base ref for template checking +PULL_BASE_SHA=origin/master make lint +``` + +### Enhancement Tools +The `tools/` directory contains a Go CLI for managing enhancements. Run from the `tools/` directory: + +```bash +# Generate weekly enhancement report +cd tools && go run ./main.go report + +# Generate annual summary +cd tools && go run ./main.go annual-summary + +# Show reviewer statistics (last 31 days) +cd tools && go run ./main.go reviewers + +# Show stale enhancement status +cd tools && go run ./main.go closed-stale --dry-run + +# Leave comments on stale enhancements +cd tools && go run ./main.go closed-stale +``` + +### Makefile Targets +```bash +# Show all available make targets +make help + +# Run weekly report generation (includes closed-stale check and linting) +make report + +# Generate annual summary +make annual-summary +``` + +## Working with Enhancements + +### Creating a New Enhancement + +1. Choose the appropriate domain directory under `enhancements/` (or use root for broad-scope enhancements) +2. Copy `guidelines/enhancement_template.md` to your chosen location +3. Fill out the YAML metadata header (required fields: title, authors, reviewers, approvers, api-approvers, creation-date, tracking-link) +4. Complete all required sections - the linter enforces this +5. Create a PR and assign domain experts as reviewers + +### Enhancement Metadata + +Each enhancement must have YAML frontmatter with: +- `title` - lowercased, spaces/punctuation replaced with `-` +- `authors` - list of GitHub handles +- `reviewers` - list of reviewers with their domain expertise +- `approvers` - single approver preferred (responsible for consensus) +- `api-approvers` - required for API changes, use "None" if no API changes +- `creation-date` - format: `yyyy-mm-dd` +- `tracking-link` - link to Jira feature/epic + +### Review Process + +- Authors manage the enhancement through review and approval +- Reviewers must include representatives from teams doing implementation work +- Approvers recognize when consensus is reached +- PRs are merged when design is complete and consensus achieved +- Implementation should ideally wait until enhancement is merged + +### Life-cycle + +- Active PRs stay open indefinitely +- Inactive PRs get `life-cycle/stale` label after 28 days +- Stale PRs become `life-cycle/rotten` after 7 more days +- Rotten PRs close after another 7 days + +## Writing Conventions + +### Terminology +- "OpenShift" or "openshift" (NEVER "Openshift") +- Use U.S. English spelling and grammar +- Always use the Oxford comma +- "bare metal" - follow the [metal3-io style guide](https://github.com/metal3-io/metal3-docs/blob/master/design/bare-metal-style-guide.md) + +### Naming Patterns +- Repository names match component names (e.g., `openshift/console-operator`) +- Image names tagged into ImageStreams match component names +- Git branches: `master` for development, `release-4.#` for maintenance +- API objects follow [Kubernetes API naming conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#naming-conventions) + +## OpenShift Architecture Concepts + +### Operator-Based Architecture +All cluster components are managed by operators that: +- Deploy, reconfigure, self-heal, and report health status +- Are coordinated by the cluster-version-operator (CVO) for core operators +- Use OLM (Operator Lifecycle Manager) for optional components with independent lifecycles + +### Global Configuration +- Exposed via API resources in `config.openshift.io` API group +- Singleton objects named "cluster" control cluster-wide settings +- `spec` contains user configuration, `status` contains system state +- Components watch/poll configuration for changes + +### High Availability Patterns +For 3-node control plane + 2-worker minimum topology: +- 2 replicas with hard pod anti-affinity on hostname +- Use maxUnavailable rollout strategy (25% default) +- For >=3 replicas on workers: soft pod anti-affinity +- Persistent storage considerations affect HA deployment + +### Priority Classes +- `openshift-user-critical` - can be preempted by user workloads +- `system-cluster-critical` - not preempted but can be OOMKilled +- `system-node-critical` - not preempted, OOMKilled last + +### Resource Requests +- Components MUST declare CPU and memory requests +- Components SHOULD NOT set resource limits +- CPU requests based on proportional baseline (etcd for control plane, SDN for all nodes) +- Memory requests: 90th percentile usage + 10% overhead + +### Metrics and Monitoring +Core operators should expose Prometheus metrics: +- Use HTTPS with TLS client certificate authentication +- Read API server's TLS security profile for allowed versions/ciphers +- Support local authorization for well-known scraping identity +- Deploy ServiceMonitors for collection by in-cluster Prometheus + +## Tools Configuration + +The enhancement tools require `~/.config/ocp-enhancements/config.yml`: + +```yaml +github: + token: "your-github-personal-access-token" +reviewers: + ignore: + - openshift-ci-robot +``` + +## Testing and CI + +- Markdown linting runs via containerized markdownlint +- Template validation ensures all required sections are present +- Metadata validation via `tools/cmd/metadataLint.go` +- Linter can be overridden if template changes after PR creation (see README for guidance) + +## Key References + +- Enhancement template: `guidelines/enhancement_template.md` +- OpenShift conventions: `CONVENTIONS.md` +- API conventions: `dev-guide/api-conventions.md` +- Breaking changes guide: `dev-guide/breaking-changes.md` +- Test conventions: `dev-guide/test-conventions.md` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..70940451a9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,5 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +Refer to @AGENTS.md for more information.