From 02a7ac4c04a2fe34b7ff1127e62986950a4fbe1e Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Fri, 27 Mar 2026 10:58:09 +0000 Subject: [PATCH 1/2] HYPERFLEET-761: Add documentation standards compliance Add CONTRIBUTING.md, CHANGELOG.md, and CLAUDE.md to meet HyperFleet documentation standards and optimize for AI agent workflows. - CONTRIBUTING.md: Development setup, repo structure, testing, commit standards, and release process - CHANGELOG.md: Keep a Changelog format with semantic versioning - CLAUDE.md: AI agent context under 200 lines with build commands, validation checklist, code conventions, and boundaries - README.md: Add Architecture repo link and Contributing section Addresses requirements from HYPERFLEET-761 for standardizing documentation across HyperFleet repositories. Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 43 ++++++++ CLAUDE.md | 265 ++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 247 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 ++ 4 files changed, 565 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f7fa23a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,43 @@ +# Changelog + +All notable changes to the HyperFleet API specification will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- CONTRIBUTING.md with development guidelines and workflow +- CHANGELOG.md following Keep a Changelog format +- CLAUDE.md with AI agent context and validation workflow + +### Changed +- Improved README.md structure to align with HyperFleet documentation standards + +## Release History + + + + +[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/HEAD diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6420dbd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,265 @@ +# HyperFleet API Spec - AI Agent Context + +This repository generates OpenAPI specifications from TypeSpec definitions. It supports multiple provider variants (core, GCP) using a shared codebase with provider-specific type aliases. + +## Quick Reference + +**Build commands:** +```bash +npm run build:core # Generate core OpenAPI spec +npm run build:gcp # Generate GCP OpenAPI spec +npm run build:all # Generate all variants with Swagger +``` + +**Validation workflow:** +```bash +npm install # Install dependencies +npm run build:core # Build and verify compilation +npm run build:gcp # Build GCP variant +ls -l schemas/*/openapi.yaml # Confirm outputs exist +``` + +## Key Concepts + +### Provider Variants via Aliases + +The repo uses a single `main.tsp` but generates different specs per provider: + +```typescript +// aliases-core.tsp +alias ClusterSpec = Record; // Generic + +// aliases-gcp.tsp +alias ClusterSpec = GCPClusterSpec; // Provider-specific +``` + +The `aliases.tsp` symlink determines which provider types are active. The `build-schema.sh` script automatically re-links this during builds. + +**When adding new models:** +- Shared models → `models/` +- Provider-specific → `models-{provider}/` +- Always update alias files if you introduce provider-specific types + +### Public vs Internal APIs + +Status endpoints are split: +- `services/statuses.tsp` - GET operations (external clients) +- `services/statuses-internal.tsp` - POST operations (internal adapters only) + +The split allows generating different API contracts per audience. Only `statuses.tsp` is imported by default. + +## Code Style + +### TypeSpec Conventions + +**Imports first, namespace second:** +```typescript +import "@typespec/http"; +import "../models/common/model.tsp"; + +namespace HyperFleet; +``` + +**Use decorators for HTTP semantics:** +```typescript +@route("/clusters") +interface Clusters { + @get list(): Cluster[] | Error; + @post create(@body cluster: ClusterInput): Cluster | Error; +} +``` + +**Model naming:** +- Resources: `Cluster`, `NodePool` (singular) +- Inputs: `ClusterInput`, `NodePoolInput` +- Provider-specific: `GCPClusterSpec`, `AWSClusterSpec` + +### File Organization + +``` +models/{resource}/ + ├── model.tsp # Shared model definitions + └── interfaces.tsp # Optional: shared interfaces + +models-{provider}/{resource}/ + └── model.tsp # Provider-specific models + +services/ + └── {resource}.tsp # Service endpoints +``` + +## Boundaries + +**DO NOT:** +- Modify generated files in `schemas/` or `tsp-output/` directly +- Add dependencies without checking TypeSpec version compatibility +- Auto-generate documentation - it degrades agent performance per research +- Use `--swagger` flag unless you need OpenAPI 2.0 for legacy tools +- Commit `node_modules/` or build artifacts + +**DO:** +- Run `npm run build:all` before committing schema changes +- Test both provider variants when modifying shared models +- Keep TypeSpec files focused (one resource per service file) +- Use semantic versioning for releases (see RELEASING.md) + +## Common Tasks + +### Add a new endpoint to existing service + +```typescript +// services/clusters.tsp +namespace HyperFleet; + +@route("/clusters") +interface Clusters { + // ... existing endpoints ... + + @get + @route("/{id}/health") + getHealth(@path id: string): HealthStatus | Error; +} +``` + +### Add a new resource + +1. Create model: +```typescript +// models/health/model.tsp +import "@typespec/http"; + +model HealthStatus { + id: string; + state: "healthy" | "degraded" | "critical"; + lastChecked: utcDateTime; +} +``` + +2. Create service: +```typescript +// services/health.tsp +import "@typespec/http"; +import "../models/health/model.tsp"; +import "../models/common/model.tsp"; + +namespace HyperFleet; + +@route("/health") +interface Health { + @get check(): HealthStatus | Error; +} +``` + +3. Import in `main.tsp`: +```typescript +import "./services/health.tsp"; +``` + +4. Build: `npm run build:core` + +### Add provider-specific fields + +```typescript +// models-gcp/cluster/model.tsp +model GCPClusterSpec { + projectId: string; + region: string; + network?: GCPNetwork; +} + +model GCPNetwork { + vpcId: string; + subnetId: string; +} +``` + +Update alias: +```typescript +// aliases-gcp.tsp +import "./models-gcp/cluster/model.tsp"; +alias ClusterSpec = GCPClusterSpec; +``` + +Build: `npm run build:gcp` + +## Validation Checklist + +Before submitting changes: + +- [ ] Dependencies installed: `npm install` +- [ ] Core variant builds: `npm run build:core` +- [ ] GCP variant builds: `npm run build:gcp` +- [ ] Schema files generated: `ls schemas/*/openapi.yaml` +- [ ] No TypeSpec compilation errors (check output) +- [ ] Changes committed including schema updates +- [ ] PR description references related issue + +## Build System Details + +**The build-schema.sh script:** +1. Validates provider parameter (core, gcp, etc.) +2. Re-links `aliases.tsp` → `aliases-{provider}.tsp` +3. Runs `tsp compile main.tsp` +4. Copies output to `schemas/{provider}/openapi.yaml` +5. (Optional) Converts to OpenAPI 2.0 with `--swagger` flag + +**Output locations:** +- TypeSpec: `tsp-output/schema/openapi.yaml` (temporary) +- Final: `schemas/{provider}/openapi.yaml` (committed) + +## VS Code Extension Notes + +The TypeSpec extension may show false errors: +- Non-active provider models appear undefined (expected) +- Duplicate type warnings from multiple alias files (expected) + +Both the CLI and "Emit from TypeSpec" command work correctly despite warnings. + +## Dependencies + +All TypeSpec libraries use version `^1.6.0` for consistency: +- `@typespec/compiler` - Core compiler +- `@typespec/http` - HTTP semantics +- `@typespec/openapi` - OpenAPI decorators +- `@typespec/openapi3` - OpenAPI 3.0 emitter +- `@typespec/rest` - REST conventions +- `@typespec/versioning` - API versioning support + +**Adding new TypeSpec libraries:** +```bash +npm install --save-dev @typespec/library-name@^1.6.0 +``` + +Match the version range to existing dependencies. + +## Release Process + +Quick reference (see RELEASING.md for details): + +```bash +# 1. Build schemas +npm run build:all + +# 2. Commit and tag +git add schemas/ +git commit -m "chore: update schemas for vX.Y.Z" +git tag -a vX.Y.Z -m "Release vX.Y.Z" + +# 3. Push tag +git push upstream vX.Y.Z + +# 4. Create GitHub Release with schema assets +gh release create vX.Y.Z \ + --repo openshift-hyperfleet/hyperfleet-api-spec \ + --title "vX.Y.Z" \ + schemas/core/openapi.yaml#core-openapi.yaml \ + schemas/gcp/openapi.yaml#gcp-openapi.yaml +``` + +## Architecture Context + +This repository is part of the HyperFleet project. For broader context: +- Architecture repo: https://github.com/openshift-hyperfleet/architecture +- Main API implementation: https://github.com/openshift-hyperfleet/hyperfleet-api + +The API implementation consumes the generated OpenAPI specs for validation and documentation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a8f95b7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,247 @@ +# Contributing to HyperFleet API Spec + +Thank you for your interest in contributing to the HyperFleet API specification! This document provides guidelines for contributing to the project. + +## Development Setup + +### Prerequisites + +- Node.js 20.x or later +- npm 11.6.2 or later (included in package.json packageManager) +- Git +- (Optional) Visual Studio Code with the TypeSpec extension + +### Initial Setup + +1. Clone the repository: + ```bash + git clone https://github.com/openshift-hyperfleet/hyperfleet-api-spec.git + cd hyperfleet-api-spec + ``` + +2. Install TypeSpec compiler globally: + ```bash + npm install -g @typespec/compiler + ``` + +3. Install project dependencies: + ```bash + npm install + ``` + +4. Verify your setup by building the schemas: + ```bash + npm run build:core + npm run build:gcp + ``` + +## Repository Structure + +``` +hyperfleet-api-spec/ +├── main.tsp # Main TypeSpec entry point +├── aliases.tsp # Active provider aliases (symlink) +├── aliases-core.tsp # Core provider aliases +├── aliases-gcp.tsp # GCP provider aliases +├── tspconfig.yaml # TypeSpec compiler configuration +├── build-schema.sh # Build script for OpenAPI generation +├── models/ # Shared models for all providers +│ ├── clusters/ # Cluster resource definitions +│ ├── nodepools/ # NodePool resource definitions +│ ├── statuses/ # Status resource definitions +│ └── common/ # Common types and models +├── models-core/ # Core provider-specific models +├── models-gcp/ # GCP provider-specific models +├── services/ # Service definitions +│ ├── clusters.tsp # Cluster endpoints +│ ├── nodepools.tsp # NodePool endpoints +│ ├── statuses.tsp # Status read endpoints (public) +│ └── statuses-internal.tsp # Status write endpoints (internal) +└── schemas/ # Generated OpenAPI outputs + ├── core/ + └── gcp/ +``` + +## Testing + +### Building Schemas + +Test your changes by building the OpenAPI schemas: + +```bash +# Build individual variants +npm run build:core +npm run build:gcp + +# Build with Swagger (OpenAPI 2.0) output +npm run build:core:swagger +npm run build:gcp:swagger + +# Build all variants +npm run build:all +``` + +### Validating Output + +After building, verify the generated schemas: + +```bash +# Check that files were generated +ls -l schemas/core/openapi.yaml +ls -l schemas/gcp/openapi.yaml + +# Review the generated OpenAPI for your changes +cat schemas/core/openapi.yaml +``` + +### Visual Studio Code Extension + +If using VS Code with the TypeSpec extension: +- The extension may show errors for non-active provider types (this is expected) +- Use "Emit from TypeSpec" command to compile +- The `build-schema.sh` script always works regardless of extension errors + +## Common Tasks + +### Adding a New Model + +1. Create the model file in the appropriate directory: + ```typescript + // models/newresource/model.tsp + import "@typespec/http"; + import "../common/model.tsp"; + + model NewResource { + id: string; + name: string; + } + ``` + +2. Import in `main.tsp` if needed +3. Build and verify: `npm run build:core` + +### Adding a New Service Endpoint + +1. Create or edit a service file in `services/`: + ```typescript + // services/newservice.tsp + import "@typespec/http"; + import "@typespec/openapi"; + import "../models/common/model.tsp"; + + namespace HyperFleet; + + @route("/new-resource") + interface NewService { + @get list(): NewResource[] | Error; + } + ``` + +2. Import in `main.tsp`: + ```typescript + import "./services/newservice.tsp"; + ``` + +3. Build and verify: `npm run build:all` + +### Adding a New Provider + +1. Create provider model directory: + ```bash + mkdir -p models-aws/cluster + ``` + +2. Define provider-specific models: + ```typescript + // models-aws/cluster/model.tsp + model AWSClusterSpec { + awsProperty1: string; + awsProperty2: string; + } + ``` + +3. Create provider aliases file: + ```typescript + // aliases-aws.tsp + import "./models-aws/cluster/model.tsp"; + alias ClusterSpec = AWSClusterSpec; + ``` + +4. Update `build-schema.sh` to support the new provider (it auto-detects) +5. Build: `./build-schema.sh aws` + +### Switching Between Providers in VS Code + +The `aliases.tsp` symlink controls which provider is active: + +```bash +# Work on Core API +ln -sf aliases-core.tsp aliases.tsp + +# Work on GCP API +ln -sf aliases-gcp.tsp aliases.tsp +``` + +The VS Code extension uses whichever provider `aliases.tsp` points to. + +## Commit Standards + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +- `feat:` - New feature or endpoint +- `fix:` - Bug fix +- `docs:` - Documentation changes +- `refactor:` - Code refactoring without functionality change +- `test:` - Adding or updating tests +- `chore:` - Build process or tooling changes + +**Examples:** +``` +feat: add NodePool autoscaling fields to GCP spec +fix: correct required fields in ClusterStatus model +docs: update README with new provider examples +refactor: consolidate common status fields +``` + +## Release Process + +See [RELEASING.md](RELEASING.md) for detailed release instructions. + +**Quick summary:** +1. Build schemas: `npm run build:all` +2. Commit changes +3. Create tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"` +4. Push tag: `git push upstream vX.Y.Z` +5. Create GitHub Release with `core-openapi.yaml` and `gcp-openapi.yaml` assets + +## Pull Request Process + +1. Create a feature branch: `git checkout -b feature/my-feature` +2. Make your changes +3. Build and test: `npm run build:all` +4. Commit with conventional commit message +5. Push to your fork +6. Create a Pull Request +7. Address review feedback +8. Wait for approval and merge + +### PR Guidelines + +- Keep PRs focused on a single change +- Include schema outputs in commits when they change +- Update documentation if you change functionality +- Reference related issues in PR description + +## Architecture and Documentation + +For broader HyperFleet architecture context and documentation standards, see the [HyperFleet Architecture Repository](https://github.com/openshift-hyperfleet/architecture). + +## Getting Help + +- Open an issue for bugs or feature requests +- Check existing issues before creating new ones +- Tag issues appropriately (bug, enhancement, documentation, etc.) + +## Code of Conduct + +Be respectful and constructive in all interactions. We aim to foster an inclusive and welcoming community. diff --git a/README.md b/README.md index f5b66a5..9a1cb17 100644 --- a/README.md +++ b/README.md @@ -252,6 +252,8 @@ The HyperFleet API provides simple CRUD operations for managing cluster resource - **Simple CRUD only**: No business logic, no event creation - **Separation of concerns**: API layer focuses on data persistence; orchestration logic is handled by external components +For broader HyperFleet architecture context and documentation standards, see the [HyperFleet Architecture Repository](https://github.com/openshift-hyperfleet/architecture). + ## Adding a New Provider To add a new provider (e.g., AWS): @@ -307,6 +309,14 @@ To add a new service (e.g., with additional endpoints): - `@typespec/openapi3` - OpenAPI 3.0 emitter - `api-spec-converter` - Converts OpenAPI 3.0 to OpenAPI 2.0 (Swagger) +## Contributing + +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for: +- Development setup and workflow +- Repository structure details +- Testing guidelines +- Commit standards +- Pull request process ## Developing with the Visual Studio Typespec extension From 8d75ca610b1bfdeb7b0c423a46b1e2eda4b35225 Mon Sep 17 00:00:00 2001 From: Angel Marin Date: Fri, 27 Mar 2026 11:48:03 +0000 Subject: [PATCH 2/2] docs: populate CHANGELOG.md with historical releases Add v1.0.0 and v1.0.2 release entries with key changes extracted from GitHub release notes. Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f7fa23a..57426a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,29 +15,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Improved README.md structure to align with HyperFleet documentation standards -## Release History - - +### Added +- Complete CRUD operations for clusters, nodepools, and statuses +- Status tracking and reporting with comprehensive history management +- Core API variant with generic cluster spec +- GCP API variant with GCP-specific cluster spec +- Kubernetes-style timestamp conventions +- List-based pagination for resource collections +- Separate public and internal status endpoints +- Interactive API documentation + +### Architecture +- Simple CRUD operations only (no business logic) +- Separation of concerns: API layer focuses on data persistence; orchestration logic handled by external components -[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/HEAD +[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.2...HEAD +[1.0.2]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/compare/v1.0.0...v1.0.2 +[1.0.0]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec/releases/tag/v1.0.0