From 4586708c06401922b9eff32b9f828015f5b085a6 Mon Sep 17 00:00:00 2001 From: Florian Forster Date: Wed, 11 Mar 2026 09:20:27 -0700 Subject: [PATCH] chore: add terminology Markdown catalog for Copilot review (#11764) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- .github/copilot-instructions.md | 1 + .../instructions/terminology.instructions.md | 16 ++++ .github/pull_request_template.md | 1 + .github/workflows/ready_for_review.yml | 1 + TERMINOLOGY.md | 82 +++++++++++++++++++ apps/docs/AGENTS.md | 1 + 6 files changed, 102 insertions(+) create mode 100644 .github/instructions/terminology.instructions.md create mode 100644 TERMINOLOGY.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6e663080d..27ec524fe 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -21,5 +21,6 @@ You are working in the ZITADEL monorepo. This codebase uses specific conventions - Use verified Nx targets only; if unsure, run `pnpm nx show 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. diff --git a/.github/instructions/terminology.instructions.md b/.github/instructions/terminology.instructions.md new file mode 100644 index 000000000..8994e07a8 --- /dev/null +++ b/.github/instructions/terminology.instructions.md @@ -0,0 +1,16 @@ +--- +applyTo: '{apps/docs/content/**/*.mdx,apps/docs/content/**/*.md,console/src/assets/i18n/*.json,apps/login/locales/*.json,internal/static/i18n/*.yaml,internal/static/i18n/*.yml,proto/**/*.proto}' +--- + +When reviewing user-facing naming changes, enforce the canonical terminology table in `TERMINOLOGY.md`. + +### How to apply +- Cross-reference every changed user-facing string against the **Search for (discouraged)** column. +- If a discouraged term is found, flag it and suggest the canonical term from **Replace with / enforce**. +- For `proto/**/*.proto` files: check comments and `description:`/`summary:` text only; do not flag identifiers, field names, or enum values. +- Only apply rules where the **Scope** column matches the file type: + - `UI` → `console/src/assets/i18n/`, `apps/login/locales/` + - `Docs` → `apps/docs/content/` + - `API` → `proto/**`, API description text + - `Everywhere` → all of the above +- If a PR introduces a new policy, setting, or resource term not yet in the table, request that the contributor adds it to `TERMINOLOGY.md`. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 979911d5a..b1158e7fc 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,6 +21,7 @@ Replace this example text with a concise list of additional changes that this PR 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 diff --git a/.github/workflows/ready_for_review.yml b/.github/workflows/ready_for_review.yml index db756633f..902c96a34 100644 --- a/.github/workflows/ready_for_review.yml +++ b/.github/workflows/ready_for_review.yml @@ -15,6 +15,7 @@ jobs: - [ ] I have reviewed my changes and would approve it - [ ] Documentations and examples are up-to-date + - [ ] Terminology updates follow issue #5888 and TERMINOLOGY.md - [ ] Logical behavior changes are tested automatically - [ ] No debug or dead code - [ ] My code has no repetitions diff --git a/TERMINOLOGY.md b/TERMINOLOGY.md new file mode 100644 index 000000000..25760925e --- /dev/null +++ b/TERMINOLOGY.md @@ -0,0 +1,82 @@ +# ZITADEL Canonical Terminology + +Authoritative naming reference derived from [issue #5888](https://github.com/zitadel/zitadel/issues/5888). +All user-facing wording in docs, UI, and API descriptions must follow this table. + +## Action values + +| Action | Meaning | +|--------|---------| +| keep | Already correct — no change needed | +| replace | Discouraged term found — use the canonical term instead | +| remove | Term must be removed entirely | +| internal | Internal use only — must not appear in user-facing text | +| proposed | Under discussion — agents should flag but not block | + +## Scope values + +| Scope | Files | +|-------|-------| +| UI | Console (`console/src/assets/i18n/`) and Login UI (`apps/login/locales/`) | +| UI + Docs | UI files plus documentation content (`apps/docs/content/`) | +| UI dialogs | Subset of UI: modal and confirmation dialog strings | +| UI section | Subset of UI: labels tied to a specific page section | +| UI indicator | Subset of UI: inline status or indicator labels | +| UI notifications | Subset of UI: toast, banner, and notification strings | +| Docs | Documentation content (`apps/docs/content/`) | +| API | Proto files and API description/comment text (`proto/**`) | +| Everywhere | UI + Docs + API | +| — | Internal only — no user-facing file scope | + +## Canonical Terminology Table + +| Canonical term | Meaning / explanation | Search for (discouraged) | Replace with / enforce | Action | Scope | +|---|---|---|---|---|---| +| Customer Portal | Central hub for all customer interactions for cloud and self-hosting customers | _(none — already canonical)_ | Customer Portal | keep | Everywhere | +| Management Console | Web interface where customers configure and manage ZITADEL resources. Must be visible as the UI app name. | Console, ZITADEL Console, Admin Console, Administration Console | Management Console | replace | UI | +| Instance | Private, isolated top-level ZITADEL environment | IAM, System, Type IAM | Instance / Type Instance | replace | Everywhere | +| Policies | Enforcement rules governing checks and constraints. Use only in enforcement contexts, always scoped (Instance / Organization). | Instance Policies, IAM Policies, Org Policies, Policies (unscoped), Instance Settings (when enforcing), Org Settings (when enforcing) | Instance Policies / Organization Policies | replace | Everywhere | +| Settings | Resource-specific configuration values (not rules). Use only in configuration contexts, always scoped (Instance / Organization). | Instance Settings, Org Settings, Instance Policies (when config), Org Policies (when config), IAM Policies (when config) | Instance Settings / Organization Settings | replace | Everywhere | +| Organization | Group of users within an instance | Organisation | Organization | replace | Everywhere | +| Organization Domain | Domain giving context where a user belongs | Primary Domain, Verified Domains, Org domains, verify your domain | Organization Domain | replace | UI + Docs | +| User (Human) | User with interactive authentication flows | Human, Human User, User: Type Human | User (Human) | replace | UI + Docs | +| Service Account | User with non-interactive authentication flows | Machine User, machine user, Service User, Machine Account, Technical Account, User: Type Machine | Service Account | replace | UI + Docs | +| User | UI display label for user identity | Display Name | User | replace | UI | +| Project | Container for applications sharing a role context | _(none — already canonical)_ | Project | keep | Everywhere | +| Project Grant | Delegation of project access to another organization | Grant, Grants, Organization Grant, Delegated Access | Project Grant / Project Grants | replace | UI + Docs | +| Application | Software or service secured using ZITADEL | _(none — already canonical)_ | Application | keep | Everywhere | +| Role Assignment | What a user is allowed to do (roles + org + user) | Authorization, external authorization, User Grant, Roles and Authorizations | Role Assignment | replace | Everywhere | +| Administrator | Role granting administrative privileges (role context only, not as a person label) | Manager, Add Manager, Add a Manager, Membership, Member, Member grants | Administrator / Add Administrator / Add an Administrator | replace | UI + Docs | +| Organization Administrators | Org-level admin role holders | ZITADEL Organization Managers | Organization Administrators | replace | UI + Docs | +| Project Administrators | Project-level admin role holders | Project A Managers | Project Administrators | replace | UI + Docs | +| Administrator Roles | Set of admin roles | Manager Roles, Membership Roles | Administrator Roles | replace | UI + Docs | +| ZITADEL Administrator Roles | ZITADEL-specific admin role set | ZITADEL Manager Roles, Zitadel Manager Roles, Zitadel Membership Roles, ZITADEL Membership Roles | ZITADEL Administrator Roles | replace | UI + Docs | +| Permission | Internal permission backing admin roles | _(internal term)_ | _(do not surface in user-facing text)_ | internal | — | +| Metadata | Key-value custom data attached to resources | Meta Data | Metadata | replace | Everywhere | +| Custom Domain | Domain identifying a ZITADEL instance (globally unique) | Custom domain, Installed domains, Instance Domains, Zitadel Domain, your_domain, your-domain | Custom Domain | replace | UI + Docs | +| Trusted Domain | Domain used for API/email contexts | _(none — already canonical)_ | Trusted Domain | keep | Everywhere | +| Passkey | Passwordless auth using device-bound credentials | passwordless, passwordless login, passwordless auth, Multifactor (fingerprint/security keys), Fingerprint, Security Keys, WebAuthn, Webauthn | Passkey | replace | UI + Docs | +| TOTP | Time-based one-time password via authenticator app | OTP (authenticator), Authenticator App | TOTP | replace | UI + Docs | +| U2F | Legacy hardware authentication (deprecated) | U2F | _(remove)_ | remove | Everywhere | +| OTP Email | One-time password delivered via email | Email OTP | OTP Email | replace | UI + Docs | +| OTP SMS | One-time password delivered via SMS | SMS OTP | OTP SMS | replace | UI + Docs | +| Organization ID | Explicit organization identifier | Resource Owner, OrgID, OrganizationID | `organization_id` | replace | API | +| Explicit object IDs | Explicit identifier per resource type | Resource ID, ResourceID | `user_id` / `project_id` / `application_id` / `instance_id` / `organization_id` | replace | API | +| Instance ID | Instance identifier label in UI | Resource Id (Instance) | Instance ID | replace | UI + Docs | +| ID | Generic identifier label in UI | Resource Id | ID | replace | UI | +| First Name | Personal given name field | Given Name | First Name | replace | Everywhere | +| Last Name | Personal family name field | Family Name | Last Name | replace | Everywhere | +| Add Administrator (dialog) | Consistent wording for admin-add dialog | Add Manager, Add a Manager | Add Administrator / Add an Administrator | replace | UI dialogs | +| Administrator (memberships section) | UI section on the user detail page showing admin memberships — should be labeled "Administrator", not "Memberships" | Memberships | Administrator | replace | UI section | +| Project Grants (section) | Project grant listing section | Grants | Project Grants | replace | UI section | +| Internal / External indicator | Shows if a user belongs to the same or a different org | _(missing indicator)_ | internal / external | replace | UI indicator | +| Password changed | Past-tense wording for password change notification | Password change | Password changed | replace | UI notifications | +| Object descriptions | All resource descriptions must use end-user language | internal / technical wording | clear end-user language | replace | UI + Docs | +| Complement Token | Flow type for actions executed during token creation. In UI use "Complement Token"; in API use `flowType = 2` (CustomiseToken). Docs must not show PreUserinfoCreation=3 for this type. | Compliment Token, CustomiseToken, CustomizeToken | Complement Token | replace | Everywhere | + +## Governance + +- **To add a new term**: open a PR that updates this table and references the decision thread. +- **Terms under discussion** may be added with action `proposed` — agents will flag but not block. +- **Ownership**: Docs + Product/UX + API maintainers approve changes to this file. +- **Source of truth for this table**: [GitHub issue #5888](https://github.com/zitadel/zitadel/issues/5888) diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md index ab42e6576..168feec89 100644 --- a/apps/docs/AGENTS.md +++ b/apps/docs/AGENTS.md @@ -13,6 +13,7 @@ The **Docs App** (`apps/docs`) hosts the ZITADEL documentation. It has recently - **Links**: Use absolute paths or standard MDX linking. - **Components**: Use only MDX components that are documented in the official Fumadocs MDX component reference and any project-specific MDX component documentation in this repo; do not introduce or rely on undocumented components. - **API Docs**: Changes in `proto/` or API response schemas often require regeneration via docs generation targets. +- **Terminology**: For user-facing naming changes in docs/UI/API descriptions, follow `TERMINOLOGY.md` (issue #5888 source). Copilot code review will flag discouraged terms automatically on PRs touching these paths. ## Verified Nx Targets - **Dev Server**: `pnpm nx run @zitadel/docs:dev`