From 6df646d61fa79d47184b78abdc5dbee04ef702fe Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Mon, 1 Jun 2026 08:11:58 +0100 Subject: [PATCH] docs(runbooks): add repository bootstrap guide --- AGENTS.md | 2 + runbooks/new-repository.md | 133 +++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 runbooks/new-repository.md diff --git a/AGENTS.md b/AGENTS.md index 0610c4a91..aa1ed0a71 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,6 +97,7 @@ For recurring organization workflows, prefer the runbooks and keep the first pas - issue and PR triage: `runbooks/triage.md` - label maintenance: `runbooks/labels.md` - project tracker automation: `runbooks/project-tracker.md` +- new-repository bootstrap: `runbooks/new-repository.md` - ADR drafting: `runbooks/adr.md` - release coordination and release-model classification: `runbooks/release.md` @@ -139,6 +140,7 @@ Do not silently work around drift. Open or update an issue in `z-shell/.github`, - `runbooks/org-review.md` - `runbooks/adr.md` - `runbooks/labels.md` +- `runbooks/new-repository.md` - `runbooks/project-tracker.md` - `runbooks/release.md` - `runbooks/triage.md` diff --git a/runbooks/new-repository.md b/runbooks/new-repository.md new file mode 100644 index 000000000..3caecbdcf --- /dev/null +++ b/runbooks/new-repository.md @@ -0,0 +1,133 @@ +# Runbook — New Repository Bootstrap + +How to create a new z-shell plugin, annex, or module repository without copying +unreviewed files from an existing project. + +**Hard rule:** keep organization-wide instructions, workflows, and issue +metadata centralized. Add child-repository files only when the repository needs +project-specific behavior. + +## Step 1 — Classify and record the repository + +1. Open a tracker issue describing the artifact, owner, consumers, and release + class from `runbooks/release.md`. +2. Choose the repository name: + - plugin: `zsh-` + - annex: `z-a-` + - compiled module: a short descriptive name +3. Add the clone to the private meta-workspace `.gitmodules` and + `workspace/repos.yml`. Do not put local paths, credentials, or machine facts + in the public repository. +4. Apply canonical labels via `runbooks/labels.md` and verify project-tracker + enrollment via `runbooks/project-tracker.md`. + +## Step 2 — Create the common repository envelope + +Every repository starts with: + +```text +LICENSE +README.md +.editorconfig +.gitignore +.github/ + workflows/ +``` + +Use the organization-approved license for the artifact. The initial `README.md` +must state the purpose, install path, supported shell/runtime, verification +command, release model, and wiki link. + +Do not copy generic `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/agents/`, or +`.github/instructions/` files into child repositories. Link to the organization +guidance when a short project-specific `AGENTS.md` is genuinely required. + +Use organization issue and pull-request templates by default. Add a child +template only when the repository has a specific intake field that the shared +template cannot express. + +## Step 3 — Add the artifact structure + +### Plugin + +```text +zsh-.plugin.zsh +functions/ # only when autoloaded functions are needed +lib/ # only when sourced helpers are needed +docs/ # short repository-local usage only +``` + +Follow the entry-point, `ZERO`, `Plugins`, guarded `fpath`, and unload patterns +in `PATTERNS.md` and the Z-Shell Plugin Standard. The unload function must +reverse plugin-owned side effects. + +### Annex + +```text +z-a-.plugin.zsh +functions/ +docs/ # short repository-local usage only +``` + +Keep annex handlers in `functions/`, start them with strict Zsh emulation, and +register only implemented handlers. Document durable ecosystem usage in the +wiki and link to it from the repository. + +### Compiled module + +Compiled modules require a design issue before scaffolding because toolchains +and loader contracts vary. The issue must define: + +- source and generated-file layout +- supported Zsh versions and platforms +- build and test commands +- install and load path +- release artifact and semantic-tag policy + +Do not invent a reusable module template from a single implementation. Add one +to this repository only after the shape is verified in multiple module repos. + +## Step 4 — Install CI from canonical templates + +Start from the organization workflow templates: + +- `workflow-templates/zsh-ci.yml` for Zsh syntax and smoke validation +- `workflow-templates/trunk.yml` for Trunk Code Quality +- `workflow-templates/project-tracker.yml` when repository issues must be + enrolled in the organization tracker + +Follow `PATTERNS.md`: pin action and reusable-workflow references to immutable +commit SHAs with readable version or branch comments. Declare top-level +permissions and concurrency for push and pull-request workflows. + +Add release automation only when the release class requires it. Plugins and +annexes consumed directly from Git usually need validation only. + +## Step 5 — Verify before publication + +Before opening the bootstrap pull request: + +1. Run `git diff --check`. +2. Parse every workflow YAML file. +3. Run the repository's syntax and smoke checks. +4. Confirm action references are immutable SHAs. +5. Confirm no generic AI orchestration files, secrets, local paths, or generated + output were added. +6. Link the tracker issue and leave an `Agent handoff` comment for deferred + template or release work. + +## Deferred template assets + +Keep this runbook as the source of truth until repeated bootstrap work proves a +stable scaffold. Create dedicated template repositories only through separate +tracked issues; do not grow this public meta-repository into a generated source +tree prematurely. + +## See also + +- `AGENTS.md` +- `PATTERNS.md` +- `runbooks/labels.md` +- `runbooks/project-tracker.md` +- `runbooks/release.md` +- `runbooks/triage.md`