Skip to content

Commit e01922c

Browse files
abramcheabramche
committed
chore(ai): add AGENTS.md to improve assisted contributions
1 parent 4b2ad6b commit e01922c

3 files changed

Lines changed: 130 additions & 7 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,3 @@
11
## Copilot Instructions for ScyllaDB Operator
22

3-
Follow the project's [CONTRIBUTING.md](../CONTRIBUTING.md) and [API_CONVENTIONS.md](../API_CONVENTIONS.md).
4-
5-
### Commits and PRs
6-
7-
- Format commit messages and PR titles as [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): `<type>(<scope>): <subject>` or `<type>: <scopeless subject>`, where subject is imperative, lowercase, ≤72 chars, and has no trailing period.
8-
- Never include `@mentions`, [keywords that close issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) or hashtag ("#") references in the commit messages.
9-
- If the PR fixes an issue, reference it with `Resolves #<number>` only in the PR description.
3+
Read and follow the instructions in [AGENTS.md](../AGENTS.md) for the full set of project conventions, build commands, architecture overview, and contribution guidelines.

‎AGENTS.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# AGENTS.md
2+
3+
This file is for AI coding agents. It describes the repository, how to build and test it, and the conventions to follow when contributing.
4+
5+
## Project Overview
6+
7+
scylla-operator is a Kubernetes operator for managing ScyllaDB clusters. It is written in Go and follows controller-runtime/kubebuilder patterns. The operator manages these primary CRDs:
8+
9+
- **ScyllaCluster** - legacy single-datacenter ScyllaDB cluster
10+
- **ScyllaDBCluster** - multi-datacenter ScyllaDB cluster
11+
- **ScyllaDBDatacenter** - per-datacenter ScyllaDB resources
12+
- **ScyllaDBMonitoring** - monitoring stack for ScyllaDB
13+
- **NodeConfig** - node-level tuning and configuration
14+
- **ScyllaOperatorConfig** - operator-wide settings
15+
16+
## Repository Layout
17+
18+
```
19+
cmd/ Entrypoints
20+
scylla-operator/ Operator binary
21+
scylla-operator-tests/ E2E test binary
22+
gen-api-reference/ API reference doc generator
23+
pkg/
24+
api/scylla/ CRD types, defaulting, validation
25+
controller/ One reconciliation controller per CRD
26+
scyllacluster/ ScyllaCluster controller
27+
scylladbcluster/ ScyllaDBCluster controller
28+
scylladbdatacenter/ ScyllaDBDatacenter controller
29+
scylladbmonitoring/ ScyllaDBMonitoring controller
30+
nodeconfig/ NodeConfig controller
31+
scyllaoperatorconfig/ ScyllaOperatorConfig controller
32+
sidecar/ Sidecar injection controller
33+
... Other supporting controllers
34+
naming/ Deterministic resource naming and label helpers
35+
scyllaclient/ HTTP client for ScyllaDB node REST API
36+
helpers/ Shared utility functions
37+
client/ Generated and extended Kubernetes clients
38+
test/ Test framework helpers
39+
test/ E2E test suites
40+
hack/ Build and CI scripts
41+
helm/ Helm charts
42+
deploy/ Static deployment manifests
43+
docs/ Generated API reference
44+
enhancements/ Design proposals
45+
examples/ Example CRD manifests
46+
assets/ Embedded assets (certs, configs)
47+
```
48+
49+
## Building and Testing
50+
51+
### Build
52+
53+
```sh
54+
make build
55+
```
56+
57+
### Unit Tests
58+
59+
```sh
60+
make test-unit
61+
```
62+
63+
### Generated Files
64+
65+
After modifying API types, CRDs, or any code that affects generated output, always run:
66+
67+
```sh
68+
make update
69+
```
70+
71+
Then verify nothing is out of date:
72+
73+
```sh
74+
make verify
75+
```
76+
77+
`make verify` will fail if generated files are stale. Always run `make update` before `make verify`.
78+
79+
### E2E Tests (Kind)
80+
81+
```sh
82+
make kind-setup # Create Kind cluster
83+
make test-e2e-kind # Run all e2e tests
84+
SO_FOCUS='test name' make test-e2e-kind # Run specific e2e test
85+
make kind-teardown # Destroy Kind cluster
86+
```
87+
88+
### Required Tools
89+
90+
yq, jq, helm, golangci-lint, operator-sdk, ginkgo, podman, kind.
91+
92+
## Architecture
93+
94+
Each CRD has a dedicated controller in `pkg/controller/<name>/`. Controllers follow the standard reconciliation loop pattern: watch the primary resource and owned/related resources, compare desired state with actual state, and apply changes.
95+
96+
- `pkg/naming/` provides deterministic resource name generation and label/selector helpers. Use it instead of constructing names manually.
97+
- `pkg/scyllaclient/` wraps the ScyllaDB node REST API for operations like health checks, repair, and configuration.
98+
- `pkg/api/scylla/` contains versioned API types (`v1`, `v1alpha1`), defaulting functions, and validation logic.
99+
- API types use a tagged/discriminated union pattern for polymorphic fields. See `API_CONVENTIONS.md` for details.
100+
101+
## Conventions for Contributions
102+
103+
### Commit Messages and PR Titles
104+
105+
Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format:
106+
107+
```
108+
<type>(<scope>): <subject>
109+
```
110+
111+
- Subject must be imperative, lowercase, 72 characters or fewer, no trailing period.
112+
- Never include `@mentions`, issue-closing keywords, or `#` references in commit messages.
113+
- If the PR fixes an issue, add `Resolves #<number>` only in the PR description body.
114+
115+
### Code Style
116+
117+
- Follow [Effective Go](https://go.dev/doc/effective_go) and [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).
118+
- Follow [Kubernetes API Conventions](https://github.com/kubernetes/community/blob/master/contributors/dml-conventions/api-conventions.md) and `API_CONVENTIONS.md` for CRD types.
119+
120+
### Before Submitting
121+
122+
1. `make build` succeeds.
123+
2. `make test-unit` passes.
124+
3. `make update` followed by `make verify` passes (no stale generated files).
125+
4. New functionality has unit tests. Integration or e2e tests where applicable.
126+
5. Commit history is clean (squash fixups, logical commits).

‎CLAUDE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Claude Code Instructions
2+
3+
Read and follow the instructions in [AGENTS.md](AGENTS.md) at the repository root for the full set of project conventions, build commands, architecture overview, and contribution guidelines.

0 commit comments

Comments
 (0)