diff --git a/.claude/skills/prepare-release/SKILL.md b/.claude/skills/prepare-release/SKILL.md index 367f80c..3050707 100644 --- a/.claude/skills/prepare-release/SKILL.md +++ b/.claude/skills/prepare-release/SKILL.md @@ -6,9 +6,15 @@ description: Prepare a new NuGet release of this repository (version bump, relea # Prepare release Prepare a new release of this NuGet package. You decide the next version -yourself. The NuGet publish itself is a **manual** GitHub Actions trigger -(`deploy-nuget.yml`, `workflow_dispatch`) and is NOT part of your job — you -prepare the repository and open the PR. +yourself. You **prepare the repository and open the release PR — then stop.** +Reviewing, merging, and publishing are **admin-only** and not part of your job: + +- You do **not** merge the release PR (or enable auto-merge). The admin reviews + and merges every PR manually. +- You do **not** trigger `deploy-nuget.yml`. The NuGet publish is a manual + `workflow_dispatch` the admin runs **after** merging the release PR. + +This skill must only be run by the admin (auto-opening PRs is admin-only). ## Workflow @@ -54,12 +60,16 @@ prepare the repository and open the PR. 11. **Release notes** — copy `.claude/skills/prepare-release/assets/release-notes.md` to `release-notes/v.md`, fill in the `{{VERSION}}`/`{{DATE}}` placeholders and the **Added / Changed / Fixed / Removed** sections (omit empty ones). + Add the new file to `OpenTelemetryExtension.slnx` (it tracks loose files + explicitly — see AGENTS.md). -12. **Commit** (no tag) — stage csproj(s), docs, release notes; message `release: v`. +12. **Commit** (no tag) — stage csproj(s), docs, release notes, `.slnx`; message `release: v`. -13. **Push & PR to main** +13. **Push & open PR to main — then stop. Do NOT merge it.** - `git push -u origin release/v` - `gh pr create --base main --head release/v --title "release: v" --body ` + - The admin reviews and merges the PR. You never merge it or enable auto-merge. -14. **Report** the PR link and remind: after merge, trigger **Deploy Nuget** manually - (Actions → Deploy Nuget → Run workflow) — it tags `v` and publishes. +14. **Report** the PR link and remind the admin: after **they** merge it, **they** + trigger **Deploy Nuget** manually (Actions → Deploy Nuget → Run workflow) — + it tags `v` and publishes. You do not trigger it. diff --git a/AGENTS.md b/AGENTS.md index 1bb3ebd..6422d14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,12 @@ release-notes/ # v{VERSION}.md per release OpenTelemetryExtension.slnx # Solution file (repo root) ``` +`OpenTelemetryExtension.slnx` lists projects **and** loose files (docs, helm +charts, release notes) explicitly. Whenever you **add, rename, move, or delete** +a tracked file — including a new `release-notes/v{VERSION}.md` — update the +`.slnx` to match, or the solution will reference a missing path or miss the new +file. + ## Branches & CI The repository follows **GitHub Flow**: `main` is the only long-lived branch and @@ -46,6 +52,23 @@ is always releasable. Packages, tags `v{VERSION}` and creates a GitHub Release from `release-notes/v{VERSION}.md`. +## Roles & permissions (admin-only actions) + +`main` is protected (PR required, `build` check must pass, `enforce_admins` on — +**nobody pushes to `main` directly, including the admin**). On top of that, the +following are reserved for the repository **maintainer (admin)** and an AI agent +must **never** do them on its own initiative: + +- **Reviewing & merging PRs into `main`.** The admin manually reviews **every** + PR and performs the merge. An agent prepares branches and **opens** PRs, then + **stops** — it does not merge them, does not enable auto-merge, and does not + merge its own PRs. +- **Opening PRs automatically.** An agent may open a PR only while explicitly + operated by the admin (e.g. the admin running the `prepare-release` skill). +- **Triggering `deploy-nuget.yml`.** Publishing (NuGet + GitHub Packages + the + `v{VERSION}` tag + GitHub Release) is a manual, admin-only `workflow_dispatch`, + run **after** the admin has merged the release PR. An agent never triggers it. + ## Public API (2 classes, minimal surface) ```csharp @@ -172,14 +195,18 @@ API to confirm the data was ingested. `src/OpenTelemetryExtension.Configuration/OpenTelemetryExtension.Configuration.csproj` (``) - Do not change `` without also creating `release-notes/v{VERSION}.md` - — the GitHub Release body is taken from that file + (and adding it to `OpenTelemetryExtension.slnx`) — the GitHub Release body is + taken from that file - NuGet publish is **manual** (`workflow_dispatch` on `deploy-nuget.yml`) — - never triggered automatically; it also creates the `v{VERSION}` git tag + never triggered automatically; it also creates the `v{VERSION}` git tag. Only + the admin triggers it, **after** merging the release PR (see + [Roles & permissions](#roles--permissions-admin-only-actions)) - The full release-prep workflow (decide SemVer, bump, update deps, build/test, end-to-end smoke test, release notes, PR to `main`) is encoded in the **`prepare-release`** skill at `.claude/skills/prepare-release/`. Run it via - Claude Code (`/prepare-release`) when cutting a release; it only prepares the - PR — publishing stays the manual `deploy-nuget.yml` trigger. + Claude Code (`/prepare-release`) when cutting a release; it only prepares and + **opens** the PR — the admin reviews and merges it, then the admin triggers + `deploy-nuget.yml`. The skill never merges or publishes. ## What NOT to do @@ -190,6 +217,10 @@ API to confirm the data was ingested. - Do not add new public API surface without a corresponding test in `TelemetryOptionsTests.cs` or `TelemetryServiceCollectionExtensionsTests.cs` - Do not add test classes without a `Category` trait (see [Tests](#tests)) +- Do not merge PRs into `main`, enable auto-merge, or trigger `deploy-nuget.yml` + — those are admin-only (see [Roles & permissions](#roles--permissions-admin-only-actions)) +- Do not add, rename, or delete a tracked file without updating + `OpenTelemetryExtension.slnx` ## Adding a new instrumentation option