mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
4586708c06
## Problem ZITADEL has inconsistent naming across docs, UI, and API ([#5888](https://github.com/zitadel/zitadel/issues/5888)). We want contributors and Copilot code-review agents to flag discouraged terms and suggest canonical replacements automatically. ## Solution Add a **Markdown terminology catalog** that Copilot agents read natively. ### What's added - **`TERMINOLOGY.md`** (repo root) — full ~35-term canonical table from issue #5888 with: - Action legend: `keep` / `replace` / `remove` / `internal` / `proposed` - Scope legend: `UI` / `Docs` / `API` / `Everywhere` - "Search for (discouraged)" and "Replace with / enforce" columns - Governance section (how to add new terms, ownership) - **`.github/instructions/terminology.instructions.md`** — Copilot `applyTo`-scoped instruction that activates on every PR touching docs/i18n/proto files and tells the agent: - Which files map to which scope - Not to flag identifiers/field names in proto files (only comments/descriptions) - To request catalog updates when new terms are introduced ### What's updated - `.github/copilot-instructions.md` — points to `TERMINOLOGY.md` - `apps/docs/AGENTS.md` — updated reference, removed dead `check-terminology` Nx target entry - `.github/pull_request_template.md` — checklist item updated - `.github/workflows/ready_for_review.yml` — checklist item updated ### Why Markdown over JSON | | Markdown | JSON | |---|---|---| | Copilot reads natively | yes | no (needs parsing context) | | Mirrors AGENTS.md table style | yes | no | | Human-readable without tooling | yes | no | | Mirrors the #5888 issue format | yes | no | | Requires schema / parser | no | yes | ### Why root over `.github/` `.github/` is for GitHub-specific automation files. `TERMINOLOGY.md` is a project-wide convention document — it belongs alongside `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `AGENTS.md` at the repo root. ## How it works in practice When a PR touches `apps/docs/content/**`, `console/src/assets/i18n/**`, `apps/login/locales/**`, or `proto/**/*.proto`, Copilot code review automatically loads `.github/instructions/terminology.instructions.md` and cross-references `TERMINOLOGY.md` to flag discouraged terms. Human reviewers see the terminology checklist in the auto-comment on PR open. ## Checklist - [x] `TERMINOLOGY.md` at repo root with all ~35 terms from #5888 - [x] Plain text action/scope values (no emojis) - [x] Copilot instruction file scoped to correct file patterns - [x] All stale `terminology-rules.json` references removed - [x] No linter/CI step added (guidelines-only approach) Relates to: #5888 --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Fabienne Bühler <[email protected]>
27 lines
1.8 KiB
Markdown
27 lines
1.8 KiB
Markdown
# GitHub Copilot Instructions for ZITADEL
|
|
|
|
You are working in the ZITADEL monorepo. This codebase uses specific conventions for its Go backend and Angular/Next.js frontends.
|
|
|
|
**CRITICAL**: Read `AGENTS.md` in the root first, then the nearest scoped `AGENTS.md` for changed files.
|
|
|
|
## Key References
|
|
- `AGENTS.md`: Root architecture map and global commands.
|
|
- `apps/api/AGENTS.md`: API app workflows and backend orchestration targets.
|
|
- `apps/login/AGENTS.md`: Specifics for the Next.js Login UI.
|
|
- `apps/docs/AGENTS.md`: Specifics for the Fumadocs documentation.
|
|
- `console/AGENTS.md`: Specifics for the Angular Console.
|
|
- `internal/AGENTS.md`: Backend domain and event-sourcing boundaries.
|
|
- `proto/AGENTS.md`: API schema and generation guidance.
|
|
- `packages/AGENTS.md`: Shared client/proto package workflows.
|
|
- `tests/functional-ui/AGENTS.md`: Cypress functional UI test workflows.
|
|
- `deploy/compose/AGENTS.md`: Docker Compose deployment invariants, file conventions, and rejected alternatives.
|
|
|
|
## Behavior
|
|
- Before Go-related work, inspect `go.mod` for required Go version/toolchain.
|
|
- Use verified Nx targets only; if unsure, run `pnpm nx show project <project>`.
|
|
- For backend changes, note we are in transition: relational data is becoming the system of record, while event writes are still required for history/audit.
|
|
- Respect terminology defined in the `Technical Glossary` section of `AGENTS.md` when generating UI text or documentation.
|
|
- For user-facing wording updates across docs/UI/API descriptions, follow the canonical table in `TERMINOLOGY.md` (issue #5888).
|
|
- Distinguish between `apps/login` (Next.js) and `console` (Angular) when suggesting frontend code.
|
|
- For deployment-related work, consult the directory-specific agents files (e.g., `deploy/compose/AGENTS.md`) for invariants, file conventions, and rejected alternatives.
|