mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 21:52:54 +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]>
34 lines
1.7 KiB
Markdown
34 lines
1.7 KiB
Markdown
<!--
|
|
Please inform yourself about the contribution guidelines on submitting a PR here: https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr. Take note of how PR/commit titles should be written and replace the template texts in the sections below. Don't remove any of the sections. It is important that the commit history clearly shows what is changed and why.
|
|
Important: By submitting a contribution you agree to the terms from our Licensing Policy as described here: https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
|
|
-->
|
|
|
|
# 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
|