BUILDING Parts of this page describe what is not built yet, and each says so.
Glossary
The glossary is the part of Governance that says what your organisation’s words mean. Each term has one definition that someone other than the person who proposed it has approved. It belongs to the organisation and not to a project, so it is the same in every project, and it reads the whole organisation whichever project is selected in the console.
Terms
A term has a name of up to 100 characters, a definition of up to 4 KiB, up to 20 synonyms, and a domain. A name has no two spaces in a row, and a synonym holds no comma: write each synonym separately. The domain is one of the organisation’s data domains and is required: a term belongs to the business area that answers for it, and that domain’s steward is the one who approves it. An organisation with no domain cannot propose a term, and the console says so and points to Stewardship.
A term’s name, its id and its domain are set when it is proposed and do not change. The id is a slug, the short name in the address of the term’s page. The console makes one from the name and you may edit it before the term exists: it starts with a lowercase letter and holds lowercase letters, digits, hyphens and underscores, up to 63 characters. A name is unique in the organisation whatever its capitals. A rejected term keeps its name until it is proposed again. Archiving a domain later leaves its terms where they are, and a new term cannot name an archived domain.
The glossary is kept by the control plane. It is not in your repository or in your data plane, and Terraform does not write it. A definition, a synonym and a rejection’s reason are text that a person typed, and the control plane keeps that text. Every member of the organisation reads every term, in every project, so write nothing in one that only some of them may see. Nothing checks it for you. A value over its limit is refused and never cut.
Versions
Every change to a term is a new version, and a version is never edited. A proposal is a draft. A version that is in force stays in force until a later version is approved. A version that someone declines is rejected, with the reason they gave, and it stays readable.
One version of a term waits at a time. While one waits, nobody can propose another: the console does not offer Edit and the control plane refuses the call by name. The person who proposed a waiting version cannot revise or withdraw it. If it has a typo, someone else rejects it with a reason and it is proposed again. Rejecting a version leaves the version in force exactly as it was.
Edit proposes the next version of a term that is approved, and it proposes a term again whose versions have all been rejected, which is how a rejected name is taken back. It changes the definition and the synonyms and nothing else. It names the version you started from, and is refused if that is no longer the version in force. A term has at most 200 versions, and an organisation at most 1,000 terms, rejected ones included.
A term’s page shows its definition, its synonyms and its versions, newest first, one line for each proposal and each decision, with the people who made them.
Who proposes and who approves
Every member of the organisation except a viewer proposes a term or a new version. That is the glossary.propose permission. A viewer reads the glossary and proposes nothing.
An owner, an admin, or the steward of the term’s domain approves or rejects a version, and never the person who proposed that version. An owner or an admin is judged by role. The steward of the domain is the person the Stewardship page names, in a signed-in session; the domain’s owner has no say over its terms. If the person who proposed a version is the organisation’s only member, they may decide it, and the audit log says the decision was self-approved. A member who has been disabled still counts as a member here, so in an organisation of an owner and a viewer, where the owner proposes, the owner cannot decide it and the viewer has no right to by role. The owner can name the viewer the steward of the term’s domain on the Stewardship page, and the viewer then approves it in a signed-in session, or the owner can make the viewer an admin.
The rule is about people, not credentials. An API token that a person made is that person for this purpose, so Alice’s token can propose a version and Alice’s own session cannot approve it. Authority by assignment counts for a signed-in session and not for an API token. A token is judged by its own role alone, so a script that approves a term needs a role that may approve, and being the domain’s steward does not add to it. An agent cannot propose, change or decide anything here: every change is refused for an agent.
Approving, rejecting and deprecating each name the version you read. If a different version is waiting by the time you decide, the control plane refuses, so you never approve text that you did not read. If two people decide at the same moment, one decision wins and the other person is told it was already decided. Rejecting needs a reason of up to 500 characters, which the person who proposed the version can read.
Deprecating a term
Deprecating says use another term instead. It names the replacement, which must be a different term whose version in force is approved and is not deprecated. Anyone who may approve the term can deprecate it, and not the person who proposed the version in force, unless they are the organisation’s only member. A term cannot be deprecated while a version of it waits.
A deprecated term stays readable and stays in the list and the export, marked as deprecated with the term to use. Nothing can be proposed for it afterwards.
Terms to approve
The Stewardship page’s Your queue has a Terms to approve section: the versions waiting that you may decide, by the rule above. An owner or an admin sees every one, because deciding them is a duty of the role. A steward sees the terms of the domains they steward, in a signed-in session. Your own proposal is not in it, unless you are the organisation’s only member. The oldest is first, and at most 50 are listed. When more wait than the control plane counted, the section’s count reads not counted instead of a number, and the list says more wait.
A row names the term, its version, its domain, the person who proposed it and when, and opens the term’s page, where it is decided. The queue decides nothing.
Reading and export
Every member reads the glossary, a viewer included, and so does an API token that may read it. The list filters by a word in a name, a synonym or a definition, by domain and by status, and reads a page at a time. Terms are the organisation’s and name no asset, so the visibility that limits what you see of the data does not limit what you see here.
Export YAML downloads the glossary as one file. It holds every domain, with its id, display name, description and whether it is archived, and the terms in force, which are the approved and the deprecated ones, with their id, name, definition, synonyms, domain and version, and for a deprecated term the term to use. It holds no draft, no rejected version, no person, no email, no time and no count of the assets a domain covers, and it is sorted, so the same glossary always exports the same bytes. Every member may export it, an agent may not, and an export is recorded in the audit log.
What the audit log keeps
Each change is in the audit log, with who made it, which term and which version. The log keeps a digest of what a person typed and never the words: not a name, a definition, a synonym or a reason. A decision made by a proposer who is the only member of the organisation is recorded with self_approved set, whether it approves, rejects or deprecates.
From the command line
The rl command does the same things. rl glossary list and
rl glossary get read, rl glossary propose and
rl glossary update propose a term and a new version, rl glossary approve,
rl glossary reject and rl glossary deprecate decide a version, and
rl glossary export prints the YAML exactly as the control plane made it; with
-out file it writes that file whole or not at all, readable by its owner only (a
file you redirect to with your shell gets your umask instead).
Terms belong to the organisation, so these commands take no project or environment. The
deciding commands name the version you read. The
command-line reference lists each command, the permission it
needs, how an idempotency key makes a retry the same change, and the exit codes.
rl signs in with an API token, so it is judged by its own role. A steward who is neither an owner nor an admin approves a term in the console, in a signed-in session, and cannot with rl.
What is not built
These are the things you might expect of a glossary that this one does not do.
- Nobody can link a term to a column or a table yet, and no link is suggested by name.
- A model does not draft a definition yet.