From 7e315595fc6d3ff6ff65fc2fae6d71c08214eda2 Mon Sep 17 00:00:00 2001 From: Jakob Jensen Date: Sun, 27 Sep 2026 00:15:43 +0200 Subject: [PATCH] chore: add context files --- AGENTS.md | 4 ++++ CODEBASE.md | 17 +++++++++++++++++ README.md | 2 +- TERMINOLOGY.md | 36 ++++++++++++++++++++++++++++++++++++ docs/HOW-TO-CONTRIBUTE.md | 6 +++--- 5 files changed, 61 insertions(+), 4 deletions(-) create mode 100644 CODEBASE.md create mode 100644 TERMINOLOGY.md diff --git a/AGENTS.md b/AGENTS.md index 7e6e7c62c..0f5658020 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -129,3 +129,7 @@ go run . verify --schema internal/configuration/schema.json --file configuration ## Maintaining AGENTS.md This file documents project conventions for agentic coding tools. Update this file to reflect changes when adding new commands, changing build processes, updating dependencies, or modifying code style conventions. Agents operating in this repository should follow the guidelines outlined here. + +When planning or reviewing changes, consult the [CODEBASE.md](./CODEBASE.md) to account for known risks and constraints involving consequential or fragile code paths, integrations, and operational workflows. This map contains selective information; the absence of an entry does not imply an area is safe or unconstrained. + +For work involving domain terms, their meanings, preferred wording, or concept relationships, read the [TERMINOLOGY.md](./TERMINOLOGY.md) in the repository root first. Use the terminology file as the source of domain vocabulary; it does not describe implementation. diff --git a/CODEBASE.md b/CODEBASE.md new file mode 100644 index 000000000..0d46436f6 --- /dev/null +++ b/CODEBASE.md @@ -0,0 +1,17 @@ +# Codebase Map + +## Overview + +CRD Catalog gathers Kubernetes CustomResourceDefinition schemas from configured sources and produces schema and definition files for downstream validation and tooling. + +## Version ordering + +- Values-file versions are sorted as semantic versions; prefixes, suffixes, and leading zeroes can produce incorrect ordering. + +## Git sources + +- Git sources are cloned with the Git CLI because cloning with the Go Git library used excessive memory. + +## Local updater check + +- `TestCheckLocal` is intended for step-debugging a local check and should be skipped during normal unit tests. diff --git a/README.md b/README.md index df7cb40f7..a1a87e0a3 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repository aggregates hundreds of popular Kubernetes CRDs (`CustomResourceD The intended purpose with this repository is aid with validation, language servers and code generation. -The catalog are checked for updates every 8 hours, but the catalog is also tagged with kubernetes versions to make the catalog available as it were when a specific version was released. +The catalog are checked for updates every 8 hours, but the catalog is also tagged with kubernetes release versions to make the catalog available as it were when a specific version was released. ## Known use cases diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md new file mode 100644 index 000000000..ceee8773f --- /dev/null +++ b/TERMINOLOGY.md @@ -0,0 +1,36 @@ +# CRD Catalog + +This domain covers the collection of Kubernetes CRDs and their schemas from external sources for use by validation and development tools. + +## Language + +**Source**: +A configured route for obtaining CRDs from an upstream. +_Avoid_: Provider, feed + +**Upstream**: +The external repository, chart repository, or service from which a source obtains CRDs. +_Avoid_: Source + +**Source version**: +A release or revision of an upstream from which CRDs are obtained. +_Avoid_: CRD version + +**CRD**: +A Kubernetes CustomResourceDefinition that establishes a custom resource kind within an API group. +_Avoid_: CRD definition + +**CRD version**: +An API version declared by a CRD. +_Avoid_: Source version + +**Schema**: +The validation schema associated with a CRD version; a CRD version may have no schema. +_Avoid_: CRD + +## Relationships + +- A **Source** obtains CRDs from an **Upstream** at a **Source version**. +- A **Source** can provide multiple **CRDs**. +- A **CRD** declares one or more **CRD versions**. +- A **Schema** belongs to a **CRD version**, and a **CRD version** may have no **Schema**. diff --git a/docs/HOW-TO-CONTRIBUTE.md b/docs/HOW-TO-CONTRIBUTE.md index deec436ba..937b20499 100644 --- a/docs/HOW-TO-CONTRIBUTE.md +++ b/docs/HOW-TO-CONTRIBUTE.md @@ -3,8 +3,8 @@ You need to create a pull request with changes to the sources list using the methods (prepared in order of preference) below: - [Helm charts](#helm-charts) -- [OCI charts](#oci-charts) - [Git](#git) +- [OCI charts](#oci-charts) - [Uris](#uris) - when everything else fails We prefer using the [Helm charts](#helm-charts) method to avoid issues like needing to specify each release version with CRD changes or version history being unavailable. @@ -119,9 +119,9 @@ This entry should contain a complete list of unique value specified in the CRDs ### `crds` -Each release version that contains addition, changes or removal to CRDs must be listed separately in this list. +Each source version that contains addition, changes or removal to CRDs must be listed separately in this list. The `baseUri` combined with each entry in `paths` using the template `${baseUri}/${pathEntry}` must be a URI to a manifest file that is publicly available. You can split the uris as you want, for instance to optimize for the longest common `baseUri`. > [!TIP] -> Each release version has their own `baseUri` and `paths` entries. +> Each source version has their own `baseUri` and `paths` entries.