mirror of
https://github.com/zitadel/zitadel.git
synced 2026-07-25 18:28:00 +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 <223556219+Copilot@users.noreply.github.com> Co-authored-by: Fabienne Bühler <fabienne@zitadel.com>
1.7 KiB
1.7 KiB
Which Problems Are Solved
Replace this example text with a concise list of problems that this PR solves. For example:
- If the property XY is not given, the system crashes with a nil pointer exception.
How the Problems Are Solved
Replace this example text with a concise list of changes that this PR introduces. For example:
- Validates if property XY is given and throws an error if not
Additional Changes
Replace this example text with a concise list of additional changes that this PR introduces, that are not directly solving the initial problem but are related. For example:
- The docs explicitly describe that the property XY is mandatory
- Adds missing translations for validations.
- Terminology updates follow issue #5888 and
TERMINOLOGY.md(including catalog updates for newly introduced terms).
Additional Context
Replace this example with links to related issues, discussions, discord threads, or other sources with more context. Use the Closing #issue syntax for issues that are resolved with this PR.
- Closes #xxx
- Discussion #xxx
- Follow-up for PR #xxx
- https://discord.com/channels/xxx/xxx