mirror of
https://github.com/outbackdingo/cozystack.git
synced 2026-01-27 10:18:39 +00:00
[docs] Add AI agent documentation structure (#1663)
## What this PR does This PR adds AI agent documentation structure to help AI coding assistants work more effectively with the Cozystack codebase. Changes: - Added `AGENTS.md` in the root with an overview and agent documentation table - Created `docs/agents/` directory with specialized agent instructions: - `overview.md` - Project structure and conventions - `contributing.md` - Git workflow, commits, and pull requests - `releasing.md` - Release process (references `docs/release.md`) - Organized documentation to make it easy for AI agents to find relevant instructions ### Release note ```release-note [docs] Add AI agent documentation structure with instructions for contributing, releasing, and project overview ```
This commit is contained in:
Andrei Kvapil
36
AGENTS.md
Normal file
36
AGENTS.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# AI Agents Overview
|
||||
|
||||
This directory contains instructions for AI coding assistants working with Cozystack.
|
||||
|
||||
## Agent Documentation
|
||||
|
||||
| Agent | Purpose |
|
||||
|-------|---------|
|
||||
| [overview.md](./docs/agents/overview.md) | Project structure and conventions |
|
||||
| [contributing.md](./docs/agents/contributing.md) | Commits, pull requests, and git workflow |
|
||||
| [releasing.md](./docs/agents/releasing.md) | Release process and workflow |
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Cozystack** is a Kubernetes-based platform for building cloud infrastructure with managed services (databases, VMs, K8s clusters), multi-tenancy, and GitOps delivery.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Code Structure
|
||||
- `packages/core/` - Core platform charts (installer, platform)
|
||||
- `packages/system/` - System components (CSI, CNI, operators)
|
||||
- `packages/apps/` - User-facing applications in catalog
|
||||
- `packages/extra/` - Tenant-specific modules
|
||||
- `cmd/`, `internal/`, `pkg/` - Go code
|
||||
- `api/` - Kubernetes CRDs
|
||||
|
||||
### Conventions
|
||||
- **Helm Charts**: Umbrella pattern, vendored upstream charts in `charts/`
|
||||
- **Go Code**: Controller-runtime patterns, kubebuilder style
|
||||
- **Git Commits**: `[component] Description` format with `--signoff`
|
||||
|
||||
### What NOT to Do
|
||||
- ❌ Edit `/vendor/`, `zz_generated.*.go`, upstream charts directly
|
||||
- ❌ Modify `go.mod`/`go.sum` manually (use `go get`)
|
||||
- ❌ Force push to main/master
|
||||
- ❌ Commit built artifacts from `_out`
|
||||
113
docs/agents/contributing.md
Normal file
113
docs/agents/contributing.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Instructions for AI Agents
|
||||
|
||||
Guidelines for AI agents contributing to Cozystack.
|
||||
|
||||
## Checklist for Creating a Pull Request
|
||||
|
||||
- [ ] Changes are made and tested
|
||||
- [ ] Commit message uses correct `[component]` prefix
|
||||
- [ ] Commit is signed off with `--signoff`
|
||||
- [ ] Branch is rebased on `upstream/main` (no extra commits)
|
||||
- [ ] PR body includes description and release note
|
||||
- [ ] PR is pushed and created with `gh pr create`
|
||||
|
||||
## How to Commit and Create Pull Requests
|
||||
|
||||
### 1. Make Your Changes
|
||||
|
||||
Edit the necessary files in the codebase.
|
||||
|
||||
### 2. Commit with Proper Format
|
||||
|
||||
Use the `[component]` prefix and `--signoff` flag:
|
||||
|
||||
```bash
|
||||
git commit --signoff -m "[component] Brief description of changes"
|
||||
```
|
||||
|
||||
**Component prefixes:**
|
||||
- System: `[dashboard]`, `[platform]`, `[cilium]`, `[kube-ovn]`, `[linstor]`, `[fluxcd]`, `[cluster-api]`
|
||||
- Apps: `[postgres]`, `[mysql]`, `[redis]`, `[kafka]`, `[clickhouse]`, `[virtual-machine]`, `[kubernetes]`
|
||||
- Other: `[tests]`, `[ci]`, `[docs]`, `[maintenance]`
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
git commit --signoff -m "[dashboard] Add config hash annotations to restart pods on config changes"
|
||||
git commit --signoff -m "[postgres] Update operator to version 1.2.3"
|
||||
git commit --signoff -m "[docs] Add installation guide"
|
||||
```
|
||||
|
||||
### 3. Rebase on upstream/main (if needed)
|
||||
|
||||
If your branch has extra commits, clean it up:
|
||||
|
||||
```bash
|
||||
# Fetch latest
|
||||
git fetch upstream
|
||||
|
||||
# Create clean branch from upstream/main
|
||||
git checkout -b my-feature upstream/main
|
||||
|
||||
# Cherry-pick only your commit
|
||||
git cherry-pick <your-commit-hash>
|
||||
|
||||
# Force push to your branch
|
||||
git push -f origin my-feature:my-branch-name
|
||||
```
|
||||
|
||||
### 4. Push Your Branch
|
||||
|
||||
```bash
|
||||
git push origin <branch-name>
|
||||
```
|
||||
|
||||
### 5. Create Pull Request
|
||||
|
||||
Write the PR body to a temporary file:
|
||||
|
||||
```bash
|
||||
cat > /tmp/pr_body.md << 'EOF'
|
||||
## What this PR does
|
||||
|
||||
Brief description of the changes.
|
||||
|
||||
Changes:
|
||||
- Change 1
|
||||
- Change 2
|
||||
|
||||
### Release note
|
||||
|
||||
```release-note
|
||||
[component] Description for changelog
|
||||
```
|
||||
EOF
|
||||
```
|
||||
|
||||
Create the PR:
|
||||
|
||||
```bash
|
||||
gh pr create --title "[component] Brief description" --body-file /tmp/pr_body.md
|
||||
```
|
||||
|
||||
Clean up:
|
||||
|
||||
```bash
|
||||
rm /tmp/pr_body.md
|
||||
```
|
||||
|
||||
## Git Permissions
|
||||
|
||||
Request these permissions when needed:
|
||||
- `git_write` - For commit, rebase, cherry-pick, branch operations
|
||||
- `network` - For push, fetch, pull operations
|
||||
|
||||
## Common Issues
|
||||
|
||||
**PR has extra commits?**
|
||||
→ Rebase on `upstream/main` and cherry-pick only your commits
|
||||
|
||||
**Wrong commit message?**
|
||||
→ `git commit --amend --signoff -m "[correct] message"` then `git push -f`
|
||||
|
||||
**Need to update PR?**
|
||||
→ `gh pr edit <number> --body "new description"`
|
||||
115
docs/agents/overview.md
Normal file
115
docs/agents/overview.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Cozystack Project Overview
|
||||
|
||||
This document provides detailed information about Cozystack project structure and conventions for AI agents.
|
||||
|
||||
## About Cozystack
|
||||
|
||||
Cozystack is an open-source Kubernetes-based platform and framework for building cloud infrastructure. It provides:
|
||||
|
||||
- **Managed Services**: Databases, VMs, Kubernetes clusters, object storage, and more
|
||||
- **Multi-tenancy**: Full isolation and self-service for tenants
|
||||
- **GitOps-driven**: FluxCD-based continuous delivery
|
||||
- **Modular Architecture**: Extensible with custom packages and services
|
||||
- **Developer Experience**: Simplified local development with cozypkg tool
|
||||
|
||||
The platform exposes infrastructure services via the Kubernetes API with ready-made configs, built-in monitoring, and alerts.
|
||||
|
||||
## Code Layout
|
||||
|
||||
```
|
||||
.
|
||||
├── packages/ # Main directory for cozystack packages
|
||||
│ ├── core/ # Core platform logic charts (installer, platform)
|
||||
│ ├── system/ # System charts (CSI, CNI, operators, etc.)
|
||||
│ ├── apps/ # User-facing charts shown in dashboard catalog
|
||||
│ └── extra/ # Tenant-specific modules, singleton charts which are used as dependencies
|
||||
├── dashboards/ # Grafana dashboards for monitoring
|
||||
├── hack/ # Helper scripts for local development
|
||||
│ └── e2e-apps/ # End-to-end application tests
|
||||
├── scripts/ # Scripts used by cozystack container
|
||||
│ └── migrations/ # Version migration scripts
|
||||
├── docs/ # Documentation
|
||||
│ ├── agents/ # AI agent instructions
|
||||
│ └── changelogs/ # Release changelogs
|
||||
├── cmd/ # Go command entry points
|
||||
│ ├── cozystack-api/
|
||||
│ ├── cozystack-controller/
|
||||
│ └── cozystack-assets-server/
|
||||
├── internal/ # Internal Go packages
|
||||
│ ├── controller/ # Controller implementations
|
||||
│ └── lineagecontrollerwebhook/
|
||||
├── pkg/ # Public Go packages
|
||||
│ ├── apis/
|
||||
│ ├── apiserver/
|
||||
│ └── registry/
|
||||
└── api/ # Kubernetes API definitions (CRDs)
|
||||
└── v1alpha1/
|
||||
```
|
||||
|
||||
## Package Structure
|
||||
|
||||
Every package is a Helm chart following the umbrella chart pattern:
|
||||
|
||||
```
|
||||
packages/<category>/<package-name>/
|
||||
├── Chart.yaml # Chart definition and parameter docs
|
||||
├── Makefile # Development workflow targets
|
||||
├── charts/ # Vendored upstream charts
|
||||
├── images/ # Dockerfiles and image build context
|
||||
├── patches/ # Optional upstream chart patches
|
||||
├── templates/ # Additional manifests
|
||||
├── templates/dashboard-resourcemap.yaml # Dashboard resource mapping
|
||||
├── values.yaml # Override values for upstream
|
||||
└── values.schema.json # JSON schema for validation and UI
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
### Helm Charts
|
||||
- Follow **umbrella chart** pattern for system components
|
||||
- Include upstream charts in `charts/` directory (vendored, not referenced)
|
||||
- Override configuration in root `values.yaml`
|
||||
- Use `values.schema.json` for input validation and dashboard UI rendering
|
||||
|
||||
### Go Code
|
||||
- Follow standard **Go conventions** and idioms
|
||||
- Use **controller-runtime** patterns for Kubernetes controllers
|
||||
- Prefer **kubebuilder** for API definitions and controllers
|
||||
- Add proper error handling and structured logging
|
||||
|
||||
### Git Commits
|
||||
- Use format: `[component] Description`
|
||||
- Always use `--signoff` flag
|
||||
- Reference PR numbers when available
|
||||
- Keep commits atomic and focused
|
||||
- Follow conventional commit format for changelogs
|
||||
|
||||
### Documentation
|
||||
|
||||
Documentation is organized as follows:
|
||||
- `docs/` - General documentation
|
||||
- `docs/agents/` - Instructions for AI agents
|
||||
- `docs/changelogs/` - Release changelogs
|
||||
- Main website: https://github.com/cozystack/website
|
||||
|
||||
## Things Agents Should Not Do
|
||||
|
||||
### Never Edit These
|
||||
- Do not modify files in `/vendor/` (Go dependencies)
|
||||
- Do not edit generated files: `zz_generated.*.go`
|
||||
- Do not change `go.mod`/`go.sum` manually (use `go get`)
|
||||
- Do not edit upstream charts in `packages/*/charts/` directly (use patches)
|
||||
- Do not modify image digests in `values.yaml` (generated by build)
|
||||
|
||||
### Version Control
|
||||
- Do not commit built artifacts from `_out`
|
||||
- Do not commit test artifacts or temporary files
|
||||
|
||||
### Git Operations
|
||||
- Do not force push to main/master
|
||||
- Do not update git config
|
||||
- Do not perform destructive operations without explicit request
|
||||
|
||||
### Core Components
|
||||
- Do not modify `packages/core/platform/` without understanding migration impact
|
||||
|
||||
29
docs/agents/releasing.md
Normal file
29
docs/agents/releasing.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Release Process
|
||||
|
||||
This document provides instructions for AI agents on how to handle release-related tasks.
|
||||
|
||||
## When to Use
|
||||
|
||||
Follow these instructions when the user asks to:
|
||||
- Create a new release
|
||||
- Prepare a release
|
||||
- Tag a release
|
||||
- Perform release-related tasks
|
||||
|
||||
## Instructions
|
||||
|
||||
For detailed release process instructions, follow the steps documented in:
|
||||
|
||||
**[docs/release.md](../release.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
The release process typically involves:
|
||||
1. Preparing the release branch
|
||||
2. Generating changelog
|
||||
3. Updating version numbers
|
||||
4. Creating git tags
|
||||
5. Building and publishing artifacts
|
||||
|
||||
All detailed steps are documented in `docs/release.md`.
|
||||
|
||||
Reference in New Issue
Block a user