diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..6540c148 --- /dev/null +++ b/AGENTS.md @@ -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` diff --git a/docs/agents/contributing.md b/docs/agents/contributing.md new file mode 100644 index 00000000..bf3aeab6 --- /dev/null +++ b/docs/agents/contributing.md @@ -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 + +# Force push to your branch +git push -f origin my-feature:my-branch-name +``` + +### 4. Push Your Branch + +```bash +git push origin +``` + +### 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 --body "new description"` diff --git a/docs/agents/overview.md b/docs/agents/overview.md new file mode 100644 index 00000000..50b9a73c --- /dev/null +++ b/docs/agents/overview.md @@ -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/// +├── 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 + diff --git a/docs/agents/releasing.md b/docs/agents/releasing.md new file mode 100644 index 00000000..b1005638 --- /dev/null +++ b/docs/agents/releasing.md @@ -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`. +