| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 4 | 5 | 0% |
| Commands | 1 | 8 | 1 | 10% |
| Section tags | 0 | 4 | 2 | 0% |
What each file covers
Sections
0 shared · 4 only in A · 5 only in B- − Repository Guidelines
- − Modules
- − Quick Commands
- − Cross-Module Rules
- + API Library Guidelines
- + Scope
- + Commands
- + Conventions
- + Boundaries
Commands
1 shared · 8 only in A · 1 only in B- − ./gradlew build
- − ./gradlew :application:test
- − pnpm -C ui typecheck && pnpm -C ui lint
- − pnpm -C ui test:unit
- − ./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen
- − gradle/libs.versions.toml
- − gradle.properties
- − git add -A
- + ./gradlew :api:test
- ./gradlew spotlessApply
Section tags
0 shared · 4 only in A · 2 only in B- − architecture
- − security
- − do-not
- − agent-behaviour
- + code-style
- + api
Line diff
halo-dev/halo · AGENTS.md
@@ −1 @@
1# Repository Guidelines
2
3Halo is a full-stack monorepo: Java 21 / Spring Boot WebFlux + R2DBC backend and a Vue 3 + TypeScript + TailwindCSS frontend. Work from the repo root and load **every relevant module guide** for the areas you touch.
4
5## Modules
6
7| Module | Path | Guide |
8|---------------------|-----------------------------------------------------------|------------------------------------------------------------------|
9| API library | `api/` (extension model, contracts, security) | [api/AGENTS.md](api/AGENTS.md) |
10| Backend application | `application/` (services, routers, migrations, packaging) | [application/AGENTS.md](application/AGENTS.md) |
11| Frontend | `ui/` (console, user center, workspace packages) | [ui/AGENTS.md](ui/AGENTS.md) |
12| Application BOM | `platform/application/` (shared dependency constraints) | [platform/application/AGENTS.md](platform/application/AGENTS.md) |
13| Plugin BOM | `platform/plugin/` (plugin-facing constraints) | [platform/plugin/AGENTS.md](platform/plugin/AGENTS.md) |
14
15## Quick Commands
16
17Run from the repo root:
18
19- `./gradlew build` — full backend build and tests.
20- `./gradlew spotlessApply` — format Java, Markdown, JSON, and properties.
21- `./gradlew :application:test` — backend tests.
22- `pnpm -C ui typecheck && pnpm -C ui lint` — frontend validation.
23- `pnpm -C ui test:unit` — frontend unit tests.
24- `./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen` — regenerate the UI client after contract changes.
25
26## Cross-Module Rules
27
28- Keep API contracts, backend handlers, and UI usage in sync; never hand-edit `ui/packages/api-client/src/` — regenerate it after contract changes.
29- Versions live in `gradle/libs.versions.toml`, `gradle.properties`, or `ui/package.json`; never hard-code them.
30- Branch naming: `feat/`, `fix/`, `improvement/`, `upgrade/`; PRs target `upstream` and follow `.github/pull_request_template.md`.
31- Stage specific files only; never `git add -A` (H2 artifacts and build outputs appear under `application/`).
32- Add tests for changed behavior; keep CI green.
33- Ask before public API changes, new dependencies, database migrations, security configuration, or CI workflow changes.
34- Never commit secrets or introduce blocking I/O into reactive flows.
35
36
halo-dev/halo · api/AGENTS.md
@@ +1 @@
1# API Library Guidelines
2
3`api/` is the public API library: the extension model, service contracts, and security abstractions consumed by the application and by plugins. Changes here affect downstream compatibility.
4
5## Scope
6
7- Source: `api/src/main/java/run/halo/app/` (core, extension, plugin, security, migration, theme, and related packages).
8- Tests: `api/src/test/`.
9
10## Commands
11
12- `./gradlew :api:test` — run API library tests.
13- `./gradlew spotlessApply` — format Java and Markdown.
14
15## Conventions
16
17- Java 21, 4-space indentation, formatted with Spotless.
18- The API is a compatibility surface: prefer additive changes, and flag any breaking signature or contract change for review before merging.
19- Extension definitions and schemas live in `application/src/main/resources/extensions/`; when you change them, update `application/` and `ui/` together.
20- Tests: JUnit 5, named `XxxTest` (unit) or `XxxIntegrationTest` (integration).
21
22## Boundaries
23
24- Public API changes in `api/` require explicit approval — treat them as affecting every plugin built against Halo.
25
26
@@ −1 +1 @@
1−# Repository Guidelines
1+# API Library Guidelines
22
3−Halo is a full-stack monorepo: Java 21 / Spring Boot WebFlux + R2DBC backend and a Vue 3 + TypeScript + TailwindCSS frontend. Work from the repo root and load **every relevant module guide** for the areas you touch.
3+`api/` is the public API library: the extension model, service contracts, and security abstractions consumed by the application and by plugins. Changes here affect downstream compatibility.
44
5−## Modules
5+## Scope
66
7−| Module | Path | Guide |
8−|---------------------|-----------------------------------------------------------|------------------------------------------------------------------|
9−| API library | `api/` (extension model, contracts, security) | [api/AGENTS.md](api/AGENTS.md) |
10−| Backend application | `application/` (services, routers, migrations, packaging) | [application/AGENTS.md](application/AGENTS.md) |
11−| Frontend | `ui/` (console, user center, workspace packages) | [ui/AGENTS.md](ui/AGENTS.md) |
12−| Application BOM | `platform/application/` (shared dependency constraints) | [platform/application/AGENTS.md](platform/application/AGENTS.md) |
13−| Plugin BOM | `platform/plugin/` (plugin-facing constraints) | [platform/plugin/AGENTS.md](platform/plugin/AGENTS.md) |
7+- Source: `api/src/main/java/run/halo/app/` (core, extension, plugin, security, migration, theme, and related packages).
8+- Tests: `api/src/test/`.
149
15−## Quick Commands
10+## Commands
1611
17−Run from the repo root:
12+- `./gradlew :api:test` — run API library tests.
13+- `./gradlew spotlessApply` — format Java and Markdown.
1814
19−- `./gradlew build` — full backend build and tests.
20−- `./gradlew spotlessApply` — format Java, Markdown, JSON, and properties.
21−- `./gradlew :application:test` — backend tests.
22−- `pnpm -C ui typecheck && pnpm -C ui lint` — frontend validation.
23−- `pnpm -C ui test:unit` — frontend unit tests.
24−- `./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen` — regenerate the UI client after contract changes.
15+## Conventions
2516
26−## Cross-Module Rules
17+- Java 21, 4-space indentation, formatted with Spotless.
18+- The API is a compatibility surface: prefer additive changes, and flag any breaking signature or contract change for review before merging.
19+- Extension definitions and schemas live in `application/src/main/resources/extensions/`; when you change them, update `application/` and `ui/` together.
20+- Tests: JUnit 5, named `XxxTest` (unit) or `XxxIntegrationTest` (integration).
2721
28−- Keep API contracts, backend handlers, and UI usage in sync; never hand-edit `ui/packages/api-client/src/` — regenerate it after contract changes.
29−- Versions live in `gradle/libs.versions.toml`, `gradle.properties`, or `ui/package.json`; never hard-code them.
30−- Branch naming: `feat/`, `fix/`, `improvement/`, `upgrade/`; PRs target `upstream` and follow `.github/pull_request_template.md`.
31−- Stage specific files only; never `git add -A` (H2 artifacts and build outputs appear under `application/`).
32−- Add tests for changed behavior; keep CI green.
33−- Ask before public API changes, new dependencies, database migrations, security configuration, or CI workflow changes.
34−- Never commit secrets or introduce blocking I/O into reactive flows.
22+## Boundaries
23+
24+- Public API changes in `api/` require explicit approval — treat them as affecting every plugin built against Halo.
3525
3626
