0 Fork 0

mirror of https://github.com/zitadel/zitadel.git synced 2026-10-25 23:50:11 -05:00

Files

T

Florian Forster 5100f2fc3f chore: add terminology Markdown catalog for Copilot review (#11764 )

## 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 <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
(cherry picked from commit 4586708c06)

2026-03-23 07:01:35 +01:00

1.8 KiB

Raw Blame History

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.

1.8 KiB Raw Blame History

GitHub Copilot Instructions for ZITADEL

Key References

Behavior

1.8 KiB

Raw Blame History