docs-stack-release

**Docs release issue** (`[Docs release] X.Y.Z` in `elastic/dev`) is the source of truth -- not the eng `[Release]` issue. Create missing docs issues (§1.1) or collect dates from the user. Missing issue URLs: `(issue TBD)`. **Playbooks:** [v9](https://github.com/elastic/docs-content-internal/blob/main/docs/releases/elastic-stack-v9.md) -- [v8](https://github.com/elastic/docs-content-internal/blob/main/docs/releases/elastic-stack-v8.md). **Templates:** [minor](https://github.com/elastic/dev/blob/main/.github/ISSUE_TEMPLATE/docs-release.md) -- [9.x patch](https://github.com/elastic/dev/blob/main/.github/ISSUE_TEMPLATE/docs-patch-release.md) -- [8.x patch](https://github.com/elastic/dev/blob/main/.github/ISSUE_TEMPLATE/docs-patch-release-8.x.md). | Line | Repo | Config files | Deploy watch | |------|------|----------------|--------------| | **9.x+** | `elastic/docs-builder` | `config/assembler.yml`, `config/versions.yml` | `docs-internal-workflows` bump PRs + prod version-bump (§0.3) | | **8.x / 7.x** | `elastic/docs` | `shared/versions/stack/*.asciidoc`, `conf.yaml` | **None** -- do not use `docs-internal-workflows` | ## Invariants - IDs, dates, PR URLs, @mentions: from `gh`, the docs issue, Slack, or the user. Never invent. Missing → `(issue TBD)` or `[@handle]` and ask. - Never mix 8.x and 9.x in one PR. 8.x/7.x: `elastic/docs` only; no `docs-internal-workflows`. - Checklist is the step index. Live-fetch only open work. RN merge is not a checkbox -- always `gh pr view` blocking RN URLs. - A PR URL in the RN table is blocking until merged. Skip only `No changes` / `N/A`. Do not exempt Fleet, Agent, or any product by name. - Check boxes this skill just completed. Do not check anyone else's work (including docs-eng). Do not wait to be asked. - Slack: read [slack-templates.md](./slack-templates.md) before drafting or sending. Confirm before send; thread follow-ups on the FF announcement. - Live/released Slack only after the **gate** (§0.3) and a user eyeball of the site. Do not draft before the gate. - Empty args / "how's my release": session state → active docs issue. Do not ask which version if one is in flight. After closed-issue cleanup leaves none, stop -- do not rediscover. - Cleanup = docs issue `CLOSED` only. 404 = drop that ID and rediscover. No TTL. - RC varies each release -- read from the `#mission-control` coordination thread or eng issue. Never hardcode a name. - Do not offer a Slack ping or PR whose issue box is already checked, or that the user already said they sent. --- ## Inputs `$ARGUMENTS` is a space-separated list of semver versions and/or `elastic/dev` issue numbers (e.g. `9.4.0 9.3.4 8.19.15` or `#1234 #1235`). If empty: load session state (§0.1). If it has an **active** release (anticipated date is today, in the last 2 days, or tomorrow, and the docs issue is not CLOSED), use that. Otherwise ask. **"How's my release" / "how's my release doing"** (no versions given): empty-args status. Load session state and run §0. Do not ask which version if an active release is in state. If cleanup left no versions, say the tracked issues are closed and stop. Match the user's request to the relevant section (status, PRs, reminders) -- they may skip the full pipeline. --- ## 0. Check status (run on every invocation) When versions or issue numbers are known (from `$ARGUMENTS` or session state), check state before proposing actions. ### 0.1 Session state (fast path) **Path:** `~/.elastic-docs/stack-release-state.json`. Local coordinator cache -- never commit it. **On every invocation:** 1. Read the file. Fall back to scratch if missing, unreadable, invalid JSON, no matching version, or the user says "start fresh". 2. Cached **IDs only** skip discovery: `docsIssue`, `engIssue`, `coordinatorPrs.{repo:{number,sha,url}}`, `rnPrs[].{product,url}`, `slack.{docsChannelId,docsFfThreadTs,missionControlChannelId,coordinationThreadTs,beginPublishingTs,handles}`, `deploys` (9.x only: `configSha`, `stagingBumpPr`, `prodBumpPr`, `stagingRunId`, `prodRunId`). Also `line`, `type`, `anticipatedDate`. 3. **Live-refresh only what the docs issue still has open** (§0.2). Do not re-`gh pr view` / `gh run view` checked lines. Always live-refresh RN PR merge state (the table stores URLs, not merge). Never trust cached JSON for merge/deploy conclusions; do trust a **checked issue line that already cites a PR or run URL**. 4. Cached ID 404 / missing message: drop that field and rediscover just that piece. Empty `slack_read_thread` on a Buildkite/bot parent (`begin publishing`, `release build declared`) is **not** a 404. 5. End of §0: drop CLOSED docs issues, then write or delete the file. `deploys` is 9.x only. Omit it for 8.x / 7.x. **Closed-issue cleanup:** Finished only if `state` is `CLOSED`. Report status this turn, then drop that version from `releases` and `active`. `announced` while OPEN is not enough. A 404 is not finished -- drop `docsIssue` and rediscover (step 4). - **Some versions still open:** write remaining entries + `updatedAt` now. Mention which version was dropped. - **None remain:** **delete** the file. Do not write `{ "active": [], "releases": {} }`. Mention that local state was cleared. ### 0.2 Stage from the docs issue (do this before extra fetches) After session state, the first GitHub call is `gh issue view`. Parse checkboxes immediately. Jump to that stage. Do not walk §1–§5. Do not re-verify checked lines. ```bash gh issue view <N> -R elastic/dev --json body,state ``` | If the issue shows | Stage | Live-fetch only | | --- | --- | --- | | Docs issue **CLOSED** | done / cleanup | None. Report closed, then closed-issue cleanup (§0.1). | | Day-before ping or coordinator-PR box **unchecked** | pre-release | Coordinator PR search (if no cached number) + RN table URLs. Skip `#mission-control` and §0.3. | | Coordinator PR **checked**, merge-RN ping **unchecked** | waiting to tell writers | RN PR states + (release day only) cached `#mission-control` threads. | | Config-merge / prod-bump (9.x) / `elastic/docs` PR (8.x) **unchecked** | waiting on publish infra | That PR/deploy (§0.3 for 9.x) + RN PR states + cached `#mission-control` threads. | | Prod-bump line **checked** with a run URL (9.x), or `elastic/docs` merge **checked** (8.x) | waiting on RNs / announce | **RN PR merge states only.** Skip coordinator `gh pr view`, bump PRs, `gh run view`. | | Website-confirm and `#mission-control` live boxes **checked** | announced | Report done. No extra fetches unless the user asks. | **RN merge is never a checkbox.** Always `gh pr view` each blocking RN URL. If a checked line's cited URL 404s, rediscover **that line only**. Stakeholder resolution (§ below): run **only** when a row still has a placeholder, a "specify who's responsible" footnote, or 2+ named people. Skip the `#docs` FF-thread search when every row already has a single named stakeholder. ### GitHub state If session state has the docs issue number, `gh issue view` it directly. Otherwise search `[Docs release] <version>`. **Do not** `gh pr list` by version if the issue or session state already has the coordinator PR URL. Search coordinator PRs only when §0.2 still needs them, **and only in the repo for that line** (9.x → `docs-builder`, 8.x → `docs`). Never `gh pr list` `elastic/docs` for a 9.x-only batch. ```bash gh pr list -R elastic/docs-builder --search "<version>" --json number,title,state,url gh pr list -R elastic/docs --search "<version>" --json number,title,state,url ``` - **Issue checkboxes:** If an item is unchecked but this skill already completed it (a Slack message you sent, a PR you opened), check it now using §4. Do not ask. Do not check items for work this skill did not do. - **RN PR status:** One shell loop over every PR URL in the Release Notes table: ```bash gh pr view <url> --json state,mergedAt,title ``` **Skip vs blocking:** Skip only `No changes` / `N/A`. A **PR URL is blocking** until merged -- do not exempt Fleet, Agent, or any other product by name. Named stakeholder is the owner; do not add `?` on a named row. Report: X/Y merged (skipping N/A rows), Z outstanding. When all blocking RN PRs are merged: "All RN PRs merged." **Then, by line -- only if §0.2 says publish infra is still open:** - **9.x:** After the `docs-builder` coordinator PR is merged **and** the prod-bump issue line is still unchecked, continue to §0.3. If that line is already checked with a run URL, skip §0.3. - **8.x / 7.x:** Skip §0.3. Config lives in `elastic/docs`. No `docs-internal-workflows` bump or deploy. ### Resolve stakeholder assignments Run only when a row still needs it (§0.2). Cases: backtick placeholder (e.g. `` `Beats point person` ``) or "specify who's responsible" footnote; 2+ named people and one confirmed in thread; named stakeholder out and someone else confirmed covering. 1. FF announcement thread (`slack_search_public` for the version in `#docs`, then `slack_read_thread`). 2. Scan replies: "I can handle [product]", "I'll do [product]", "I'm drafting the X.Y.Z [product] release notes", or explicit coverage. 3. Reverse-map Slack display name → GitHub handle via the issue appendix lookup table. If missing, `slack_search_users` and ask the user for the GitHub handle. 4. Update the issue body (§4): replace placeholder, narrow to the confirmed person, or swap in the covering person. 5. Report: "Updated [Product] stakeholder: [old] → @new-handle (confirmed in thread)." No confirmation: leave as-is and flag. Do not guess. Ambiguous ("I can help" with no product): ask. ### #mission-control (release day only) If session state has thread timestamps, `slack_read_thread` those first. **Do not** `slack_read_channel` the whole of `#mission-control`. **Do not** `slack_search_public` for `"begin publishing"` without a version **and** `after:` today's date. Empty thread on `beginPublishingTs` / `releaseBuildDeclaredTs` is expected for Buildkite bot posts. Treat the parent as the signal; do not rediscover. Only search when a **needed** cached ts is missing (not merely an empty thread): `slack_search_public` query like `9.5.2 in:#mission-control after:YYYY-MM-DD`, limit 5. Signals matching tracked versions (link each thread in the status report): 1. **Coordination thread:** "Coordination for ... release, scheduled on" -- timing, who's RC (never assume), schedule changes in replies. 2. **"release build declared":** "We are officially declaring X.Y.Z as the release build". 3. **"begin publishing":** "All pre-finalize steps for X.Y.Z are complete. Please begin the publishing process." -- docs action trigger. Read for go/hold from **whoever is RC** (step 1). ### 0.3 Watch `docs-internal-workflows` (**9.x only**) **Skip this section for 8.x / 7.x.** Do not search that repo, do not poll bump PRs or version-bump runs, and do not require a prod version-bump for 8.x live messages. **Skip §0.3** when the docs issue already checks the "Watch for the prod version-bump deploy" line (or equivalent) and cites a successful prod run URL. Do not re-list bump PRs or re-view runs. For **9.x**, after the `docs-builder` coordinator PR merges **and** that issue line is still unchecked: The coordinator merges docs-builder config PRs and watches the prod version-bump. Do not wait on docs engineering. Merging the coordinator PR (config SHA = merge commit short SHA) automatically opens: - `[bump] [staging] docs-builder configuration: <sha>` - `[bump] [prod] docs-builder configuration: <sha>` Those merges kick off `Staging / Docs / Deploy / version-bump / ...` and `Prod / Docs / Deploy / version-bump / ...`. Care about two things only: 1. **Bump PRs merged** -- staging and prod `[bump] ... <sha>` are `MERGED`. 2. **Prod version-bump deploy succeeded** for that SHA. A **failed staging** version-bump **blocks** -- report immediately; do not treat prod as done. Ignore unrelated workflows (edge, AI enrich, zizmor, dependabot, assembler ingest, link-index) unless the user asks. Do not wait on staging **success** once prod has succeeded, as long as staging did not **fail**. ```bash gh pr list -R elastic/docs-internal-workflows --state all \ --search "[bump] docs-builder configuration: <sha>" \ --json number,title,state,mergedAt,url gh run list -R elastic/docs-internal-workflows --limit 20 \ --json name,conclusion,status,displayTitle,url,databaseId,createdAt ``` Match runs by `version-bump` in the name plus timing after the bump PR merge. Cache bump PR numbers and run IDs. When prod version-bump is `completed/success` and staging did not fail: "Prod deploy succeeded for <sha>." **Gate -- do not draft "docs are live" / "docs released" until all required:** | Line | Gate | |------|------| | **9.x** | All blocking RN PRs merged **and** prod version-bump succeeded (staging did not fail) | | **8.x / 7.x** | All blocking RN PRs merged **and** the `elastic/docs` coordinator PR is merged | Until the gate is met: do not draft those messages, do not ask "ready to send?", do not check website-confirm or `#mission-control` boxes. Once the gate is met: ask the user to **eyeball the website**, then §6.5. Visual check is required before sending. 8.x "docs released" still includes the scrape line. ### Propose next action Summarize the §0.2 stage, what is still blocking, and the **single** next action. Do not offer a Slack ping or PR whose box is already checked / the user already sent. --- ## 1. Gather inputs - Semver list. - **Docs release issue(s)** -- `[Docs release] X.Y.Z`, not the eng release issue. `gh issue list -R elastic/dev --search "[Docs release] <version>" --json number,title,url`. - **Eng release issue** -- RC's parent (`[Release] X.Y.Z`, `X.Y.Z release`, etc.). Canonical schedule (FF, GA), often links to docs issues, identifies the RC. Use for dates when the docs issue does not exist yet, which versions share a GA, and RC name. - If docs issues don't exist yet, §1.1.