Agentic-docs: Part-1: Add agentic documentation foundation and domain knowledge#2026
Agentic-docs: Part-1: Add agentic documentation foundation and domain knowledge#2026Prashanth684 wants to merge 1 commit into
Conversation
Introduce ai-docs/ directory with foundational navigation and core platform concepts to enable AI-assisted development workflows. Foundation (Navigation & Principles): - AGENTS.md: Navigation index with task-based flows - CLAUDE.md: Symlink for AI agent compatibility - ai-docs/DESIGN_PHILOSOPHY.md: Core principles and patterns - ai-docs/KNOWLEDGE_GRAPH.md: Visual concept map - ai-docs/references/: Glossary and reference index Domain Knowledge (Platform Concepts): - ai-docs/domain/kubernetes/: Pod, Service, CRD patterns - ai-docs/domain/openshift/: ClusterOperator, ClusterVersion APIs - ai-docs/platform/operator-patterns/status-conditions.md: Condition patterns - ai-docs/platform/openshift-specifics/upgrade-strategies.md: Upgrade safety Workflows: - ai-docs/workflows/topology-considerations-guide.md: SNO, MicroShift, Hypershift This establishes the framework for subsequent operator patterns, workflows, and practices documentation. Related: openshift#1992
|
@Prashanth684: No Jira issue with key Part-1 exists in the tracker at https://redhat.atlassian.net. DetailsIn 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. |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
@Prashanth684: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions 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. |
|
|
||
| - name: v1beta1 | ||
| served: true | ||
| storage: false # Deprecated but still served |
There was a problem hiding this comment.
Deprecated is an actual field which isn't demonstrated in this example, so this comment feels inaccurate to me
| openAPIV3Schema: {...} | ||
| ``` | ||
|
|
||
| ### Conversion Webhook |
There was a problem hiding this comment.
Should we note that in openshift we typically do not serve multiple versions and therefore do not need conversion webhooks?
| **Benefits**: | ||
| - Separate RBAC for spec vs status | ||
| - Update status without triggering validation webhooks on spec | ||
| - ObservedGeneration pattern |
There was a problem hiding this comment.
Cannot update spec from status endpoint, cannot update status from primary endpoint
|
|
||
| 1. **Schema Validation**: Define comprehensive OpenAPI schema | ||
| - Prevent invalid objects from being created | ||
| - Better than validating in controller |
There was a problem hiding this comment.
Mention that we aim for synchronous validation at admission time?
| 5. **Short Names**: Provide kubectl shortcuts | ||
| ```yaml | ||
| shortNames: [co] # kubectl get co | ||
| ``` |
There was a problem hiding this comment.
We don't normally recommend short names. We only allow them on objects we expect to be used frequently by the majority of cluster users, which precludes most openshift APIs
| ### By Keyword | ||
|
|
||
| ```bash | ||
| # Search GitHub org | ||
| https://github.com/orgs/openshift/repositories?q=<keyword> | ||
|
|
||
| # Example: storage-related repos | ||
| https://github.com/orgs/openshift/repositories?q=storage | ||
| ``` | ||
|
|
||
| ### By Topic | ||
|
|
||
| ```bash | ||
| # Operator repos | ||
| https://github.com/orgs/openshift/repositories?q=operator | ||
|
|
||
| # API repos | ||
| https://github.com/orgs/openshift/repositories?q=api | ||
| ``` |
| | `cluster-<component>-operator` | `cluster-etcd-operator` | Core platform | | ||
| | `<component>-operator` | `machine-api-operator` | Platform feature | |
There was a problem hiding this comment.
Not really... All operators should have had the cluster prefix, but it doesn't really mean anything, it was just so that the operators were grouped together in a dir structure. There's no semantic meaning that can be gleaned from whether an operator has or has not the cluster prefix
|
|
||
| ```bash | ||
| # View owners | ||
| curl https://raw.githubusercontent.com/openshift/<repo>/master/OWNERS |
There was a problem hiding this comment.
Majority of repos now use main not master
| ↓ | ||
| status-conditions.md (how to report health) | ||
| ↓ | ||
| clusteroperator.md (how CVO sees your operator) |
There was a problem hiding this comment.
Will we eventually have a path for non core operators?
| 1. **Foundation** (5 min): DESIGN_PHILOSOPHY.md | ||
| 2. **Your task** (10 min): 2-3 docs from task path above | ||
| 3. **Details** (20 min): Related patterns/concepts as needed |
There was a problem hiding this comment.
Where did these time estimates come from? Are they for AI or humans?
3 participants
Introduce ai-docs/ directory with foundational navigation and core platform concepts to enable AI-assisted development workflows.
Foundation (Navigation & Principles):
Domain Knowledge (Platform Concepts):
Workflows:
This establishes the framework for subsequent operator patterns, workflows, and practices documentation.
Related: #1992