From 989c97e02353efd2e8609898d3cf4063369ba530 Mon Sep 17 00:00:00 2001 From: George Karr Date: Mon, 25 Aug 2025 13:52:53 -0500 Subject: [PATCH] Adding stub for additional ritual documentation to help add clarity but not overwhelm the handbook with too many details (#31872) --- docs/Contributing/rituals/README.md | 37 +++++++++++++++++++++++++++++ docs/Contributing/rituals/scrum.md | 34 ++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/Contributing/rituals/README.md create mode 100644 docs/Contributing/rituals/scrum.md diff --git a/docs/Contributing/rituals/README.md b/docs/Contributing/rituals/README.md new file mode 100644 index 0000000000..4af128ea23 --- /dev/null +++ b/docs/Contributing/rituals/README.md @@ -0,0 +1,37 @@ +## Engineering rituals + +This folder contains concise, tactical guides for the recurring engineering rituals ("ceremonies") practiced at Fleet. These docs exist to make the rituals easy to run and improve by: + +* Clarifying purpose (why we do the ritual) +* Listing roles, inputs, and expected outputs +* Supplying lightweight agendas / checklists and any timeboxes +* Capturing tips, gotchas, and decision charts that help them run smoothly + +Authoritative definitions of process and policy live in the public Fleet handbook (https://fleetdm.com/handbook). Ritual docs here are intentionally practical and should avoid duplicating full policy text. When a definition changes in the handbook, update links or brief summaries here (do not fork the process). + +### Adding or updating a ritual doc + +1. Create a new markdown file named after the ritual (e.g. `sprint-demo.md`, `oncall-handoff.md`). +2. Start with an `## Overview` section (Purpose, Cadence, Participants, Primary artifacts). +3. Provide an Agenda / Flow section with ordered or bulleted steps and explicit timeboxes where useful. +4. Include decision aids (Mermaid diagrams, tables) only when they accelerate the ritual (keep them small and actionable). +5. Link to the relevant handbook sections for deeper context instead of duplicating content. +6. Keep the tone instructional and brief. Remove information that drifts into historical narrative. +7. Add the new file to the list below. + +### Current ritual docs + +* [Scrum](./scrum.md) – daily standup focus and incoming bug review flowchart (overview + decision chart). Canonical process: https://fleetdm.com/handbook/company/product-groups#scrum-at-fleet + +### Future candidates (create when there is persistent friction) + +These are examples; only add if a stable, repeatable ritual with clear ownership emerges: + +* Sprint demo (live run checklist, recording tips) +* Sprint retrospective variations +* Estimation session facilitation +* Incident review (if / when standardized beyond existing handbook guidance) + +### Maintenance + +Ritual owners (usually the EM or designated facilitator) should review their doc at least quarterly, or immediately after a retrospective surfaces a change. Keep PRs small and link to the retrospective or decision that prompted the update. diff --git a/docs/Contributing/rituals/scrum.md b/docs/Contributing/rituals/scrum.md new file mode 100644 index 0000000000..e15cca1c1a --- /dev/null +++ b/docs/Contributing/rituals/scrum.md @@ -0,0 +1,34 @@ +## [Daily Standup](https://fleetdm.com/handbook/company/product-groups#sprint-ceremonies) + +Purpose: Provide a fast daily synchronization point for the product group and a quick triage of freshly reported bugs awaiting reproduction. + +Cadence: Daily on all working days of the sprint (3‑week sprint cadence aligned with Fleet release cycle). + +Participants: Entire product group (engineers, EM, PD as needed). QA engineer (or whoever is wearing the QA hat) explicitly called out during the incoming bug review step. + +Agenda: +* What changed since yesterday / what will change before tomorrow +* Review incoming bugs for your team. +* Blockers (surface, not solve in-room) + +Out of scope: Deep design debates, estimation, and retro topics (park these and spin off after the ritual with only needed folks). + +Handbook reference (authoritative process + item definitions): https://fleetdm.com/handbook/company/product-groups#scrum-at-fleet + +## Incoming bug review + +Here is a simple decision chart to make reviewing new incoming bugs with the team quick during scrum. + +```mermaid +flowchart TD + A[Is this a bug?] -->|Yes| B[Assign QA engineer timebox 30–60 min later today] + A -->|No| C[Close with comment] + + B --> D[QA reproduces bug?] + D -->|Yes| E[Move to Inbox Add :product, remove :reproduce] + D -->|No| F[Comment asking for more info. If it's a customer reported bug, add :help-customers] + + F --> G[Wait 1 week for response] + G -->|No response| H[Close with comment Can reopen if more info provided] + G -->|Response| B +``` \ No newline at end of file