From 0c2246e409a5ec334fa80dfa79cf60f9652ef653 Mon Sep 17 00:00:00 2001 From: simonfaltum Date: Tue, 16 Jun 2026 12:07:44 +0200 Subject: [PATCH] Add onboard-team-area skill Encodes the repeatable steps for onboarding a new team or reserving a new code area in the CLI: add the team to .github/OWNERTEAMS, reserve experimental// and acceptance/experimental//, and map both paths in .github/OWNERS so the maintainer-approval gate routes the area's PRs to the team. Mirrors PR #5605. Includes a short experimental-vs-stable note and a pointer to the aitools graduation (PR #4917) so a new team knows where code lives and how it later moves to a stable top-level command. Co-authored-by: Isaac --- .agent/skills/onboard-team-area/SKILL.md | 64 ++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .agent/skills/onboard-team-area/SKILL.md diff --git a/.agent/skills/onboard-team-area/SKILL.md b/.agent/skills/onboard-team-area/SKILL.md new file mode 100644 index 00000000000..d849e17db2d --- /dev/null +++ b/.agent/skills/onboard-team-area/SKILL.md @@ -0,0 +1,64 @@ +--- +name: onboard-team-area +description: "Onboard a new team or reserve a new code area in the Databricks CLI: add the team to .github/OWNERTEAMS, reserve experimental// and acceptance/experimental//, and map both paths in .github/OWNERS so the maintainer-approval gate routes the area's PRs to the team. Use when the user says 'onboard a team', 'add an OWNERS team', 'reserve an experimental area', 'add a new team to the CLI', or wants a new owned directory wired into review." +user-invocable: true +allowed-tools: Read, Edit, Write, Bash, Glob, Grep, AskUserQuestion +--- + +# Onboard a team / area into the CLI + +How ownership works here: `.github/OWNERS` is CODEOWNERS-style and last-match-wins. `.github/OWNERTEAMS` maps `team:` to an explicit `@member` list and is the source of truth, because the CI token cannot resolve GitHub org-team membership. The `maintainer-approval` workflow is a required check that blocks merge until every owned group a PR touches has at least one approval from one of its owners. + +Worked example: PR #5605 ("Add ai-training OWNERS team and reserve experimental/air") is exactly the steps below: +1 line in OWNERTEAMS, two `.gitkeep` files, +2 lines in OWNERS. + +## Inputs (ask if missing) + +- Team alias, e.g. `ai-training`, and the `@member` list. +- Area/dir name, e.g. `air`. +- Experimental or stable? This decides where code lands (see the last section). + +## Step 1 — Add the team to `.github/OWNERTEAMS` + +Append one line, keeping the existing column alignment: + +``` +team: @member1 @member2 ... +``` + +If the team has a GitHub team page, add its URL to the header comment block. Skip the URL if the team page does not exist yet; the validator only warns about a missing URL, it does not block. + +## Step 2 — Reserve the directories + +Create empty `.gitkeep` placeholders so the owned paths exist before any code lands: + +``` +experimental//.gitkeep +acceptance/experimental//.gitkeep +``` + +## Step 3 — Map the paths in `.github/OWNERS` + +Add rules under an `# ` comment. Because last-match-wins, specific rules go after the `*` maintainer catch-all: + +``` +/experimental// team: +/acceptance/experimental// team: +``` + +## Step 4 — Validate and open the PR + +```bash +# OWNERS parser + approval-logic tests +node --test .github/scripts/owners.test.js .github/workflows/maintainer-approval.test.js +# OWNERS/OWNERTEAMS consistency: undefined teams, zero-owner rules, missing paths +node .github/scripts/owners.js validate +# Repo quick checks (no Go/Python/YAML changed, so the formatters have nothing to do) +./task checks +``` + +No `NEXT_CHANGELOG.md` entry; this is ownership/config only. Write the PR using the `.github/PULL_REQUEST_TEMPLATE.md` sections (Why / Changes / Tests). + +## Experimental vs stable, and graduation + +- **Experimental** — code under `experimental//`, tests under `acceptance/experimental//`. Register it under the hidden parent in `cmd/experimental/experimental.go`, or top-level in `cmd/cmd.go` with `Hidden: true` (as `ssh` does). Experimental commands still ship enabled in every release; `Hidden` only removes them from `--help`, it does not gate or compile them out. No `NEXT_CHANGELOG` entries while experimental. To hand a build to testers, push a `bugbash-` branch (auto-builds a snapshot) and share the `internal/bugbash/exec.sh` one-liner. +- **Graduating to stable** — `git mv` the feature-complete commands to `cmd//` + `libs//`, register them top-level in `cmd/cmd.go`, keep the old `experimental` paths as deprecated cobra aliases (`sub.Hidden = true`, `sub.Deprecated = '...'`), add OWNERS rules for the new stable paths, and add the `NEXT_CHANGELOG` entry. See `experimental/aitools` graduating to top-level `aitools` (PR #4917) as the worked example.