Repository governance from the contracts: owners, the file, the config.
Each package's workshop.toml names who reviews it ([owners]
with users, teams, and approvals); the root contract's
own [owners] guard the governance declarations themselves, so
raising a reviewer count is a reviewed merge like any change. This
module turns those declarations into the forge's CODEOWNERS file (a
managed generated artifact the drift gate compares offline), into
the repository settings configure asserts, and into the
generated post-merge workflow that applies them, so nobody carries
forge-specific knowledge in their head.
Functions:
| Name |
Description |
owners_of |
A contract's (users, teams, approvals) owner declaration.
|
offline_forge |
The contract's forge backend with no credential attached.
|
governance_entries |
The neutral ownership declarations, root guard first.
|
codeowners_file |
The rendered codeowners artifact, or None with no declarations.
|
governance_paths |
The paths whose change means governance may need re-applying.
|
governance_config |
The approvals half of the repository settings.
|
unknown_owners |
Declared owners the forge does not know, for configure's check.
|
owners_of
A contract's (users, teams, approvals) owner declaration.
Approvals default to zero: declared owners document and route
review without gating the merge until a count is asked for,
which is what a solo maintainer needs (a forge that forbids
self-approval deadlocks a solo repo on any required review).
Source code in packages/workshop/src/livery/workshop/_governance.py
| def owners_of(contract: dict[str, Any]) -> tuple[tuple[str, ...], tuple[str, ...], int]:
"""A contract's ``(users, teams, approvals)`` owner declaration.
Approvals default to zero: declared owners document and route
review without gating the merge until a count is asked for,
which is what a solo maintainer needs (a forge that forbids
self-approval deadlocks a solo repo on any required review).
"""
table = _owners_table(contract)
users = tuple(str(name) for name in table.get("users", []) if str(name).strip())
teams = tuple(str(name) for name in table.get("teams", []) if str(name).strip())
approvals = int(table.get("approvals", 0))
return users, teams, approvals
|
offline_forge
The contract's forge backend with no credential attached.
The codeowners rendering is pure string building, so the drift
gate may hold a backend offline; nothing built here may be used
for a network call.
Source code in packages/workshop/src/livery/workshop/_governance.py
| def offline_forge(root: Path) -> Forge:
"""The contract's forge backend with no credential attached.
The codeowners rendering is pure string building, so the drift
gate may hold a backend offline; nothing built here may be used
for a network call.
"""
from livery.forge import GiteaForge, GithubForge, GitlabForge
contract = load_contract(root / "workshop.toml")
table = contract.get("forge") or {}
kind = str(table.get("kind", ""))
url = str(table.get("url", ""))
if kind == "github":
return GithubForge.connect(url=url, token="")
if kind == "gitea":
return GiteaForge.connect(url=url or "http://offline.invalid", token="")
if kind == "gitlab":
return GitlabForge.connect(url=url or "http://offline.invalid", token="")
fail(f"unknown forge kind {kind!r}: use github, gitea, or gitlab")
|
governance_entries
The neutral ownership declarations, root guard first.
The root contract's owners guard the root workshop.toml and
the rendered codeowners file itself (config-as-code guarded by
itself); each package's owners guard its directory. A workspace
with no owner declarations anywhere answers empty, and no file
is generated.
Source code in packages/workshop/src/livery/workshop/_governance.py
| def governance_entries(root: Path) -> tuple[CodeownersEntry, ...]:
"""The neutral ownership declarations, root guard first.
The root contract's owners guard the root ``workshop.toml`` and
the rendered codeowners file itself (config-as-code guarded by
itself); each package's owners guard its directory. A workspace
with no owner declarations anywhere answers empty, and no file
is generated.
"""
from livery.workshop._packages import discover_packages
contract = load_contract(root / "workshop.toml")
forge_table = contract.get("forge") or {}
owner = str(forge_table.get("owner", ""))
if not str(forge_table.get("kind", "")):
# No forge declared: nothing to render a dialect for, and a
# bare rig must not be forced to invent one.
return ()
def _qualified(users: tuple[str, ...], teams: tuple[str, ...]) -> tuple[str, ...]:
return users + tuple(f"{owner}/{team}" for team in teams)
entries: list[CodeownersEntry] = []
root_users, root_teams, root_approvals = owners_of(contract)
rendered_path = offline_forge(root).codeowners(()).path
if root_users or root_teams:
guard = _qualified(root_users, root_teams)
entries.append(
CodeownersEntry(
path="/workshop.toml", owners=guard, min_approvals=root_approvals
)
)
entries.append(
CodeownersEntry(
path=f"/{rendered_path}", owners=guard, min_approvals=root_approvals
)
)
if (root / "packages").is_dir():
for package in discover_packages(root):
contract_file = package.directory / "workshop.toml"
users, teams, approvals = owners_of(load_contract(contract_file))
if not (users or teams):
continue
entries.append(
CodeownersEntry(
path=f"/{package.path}/",
owners=_qualified(users, teams),
min_approvals=approvals,
)
)
return tuple(entries)
|
codeowners_file
The rendered codeowners artifact, or None with no declarations.
Source code in packages/workshop/src/livery/workshop/_governance.py
| def codeowners_file(root: Path) -> Codeowners | None:
"""The rendered codeowners artifact, or None with no declarations."""
entries = governance_entries(root)
if not entries:
return None
return offline_forge(root).codeowners(entries)
|
governance_paths
The paths whose change means governance may need re-applying.
Source code in packages/workshop/src/livery/workshop/_governance.py
| def governance_paths(root: Path) -> tuple[str, ...]:
"""The paths whose change means governance may need re-applying."""
paths = ["workshop.toml", "packages/*/workshop.toml"]
rendered = codeowners_file(root)
if rendered is not None:
paths.append(rendered.path)
return tuple(paths)
|
governance_config
The approvals half of the repository settings.
The repo-wide count is the highest any declaration asks, because
GitHub and Gitea express one count through protection; GitLab's
per-path sections carry the rest, where a paid tier enforces
them. No declarations anywhere means no approval requirement.
Source code in packages/workshop/src/livery/workshop/_governance.py
| def governance_config(root: Path) -> RepoConfig:
"""The approvals half of the repository settings.
The repo-wide count is the highest any declaration asks, because
GitHub and Gitea express one count through protection; GitLab's
per-path sections carry the rest, where a paid tier enforces
them. No declarations anywhere means no approval requirement.
"""
entries = governance_entries(root)
if not entries:
return RepoConfig()
highest = max(entry.min_approvals for entry in entries)
# A count of zero asserts zero and requires no codeowner review
# either: on a forge that forbids self-approval, a codeowner
# requirement alone still deadlocks a solo repo, and ownership
# stays documented in the file.
return RepoConfig(
min_approvals=highest,
require_codeowner_review=highest > 0,
)
|
unknown_owners
Declared owners the forge does not know, for configure's check.
Users are checked against members(owner), teams against
teams(owner); the answers are live listings, so this runs
only where the forge is already being spoken to, never on the
merge path.
Source code in packages/workshop/src/livery/workshop/_governance.py
| def unknown_owners(root: Path, forge: Forge, owner: str) -> tuple[str, ...]:
"""Declared owners the forge does not know, for configure's check.
Users are checked against ``members(owner)``, teams against
``teams(owner)``; the answers are live listings, so this runs
only where the forge is already being spoken to, never on the
merge path.
"""
members = set(forge.members(owner))
teams = set(forge.teams(owner))
missing: list[str] = []
for entry in governance_entries(root):
for name in entry.owners:
_, slash, team = name.partition("/")
if slash:
if team not in teams and name not in teams:
missing.append(f"team {name} (declared on {entry.path})")
elif name not in members:
missing.append(f"user {name} (declared on {entry.path})")
return tuple(dict.fromkeys(missing))
|