From 0f8ea61dd319c93b25d44fa2a80cc187094f15f4 Mon Sep 17 00:00:00 2001 From: Chris Aigner Date: Fri, 22 May 2026 10:24:46 +0200 Subject: [PATCH 1/5] docs(sdk): Expand project setup and close-out guidance in Linear playbook Add a structured project description template with copyable markdown, split required project fields into MUST/SHOULD/MAY tiers, and expand the Closing Out section with an artifact checklist, communication checklist, and follow-up reminders. Also add a cross-reference from the planning-scoping DoD standard to the new artifact checklist. Co-Authored-By: Claude Co-authored-by: Cursor --- .../coordination/managing-linear-projects.mdx | 77 ++++++++++++++++++- .../standards/planning-scoping.mdx | 2 + 2 files changed, 78 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx index 1a26c35988869..2d4e07fff5347 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx @@ -104,10 +104,54 @@ You **MUST** set all of the following attributes before sharing the project with - **Status**: set to the appropriate state (`Planned`, `In Progress`, etc.) - **Target date**: realistic delivery date; **MUST** be set before the project moves to **In Progress** - **Team**: the owning SDK team -- **Description**: scope, goals, and non-goals; detailed enough that a new team member can orient themselves without asking +- **Description**: use the structured template below; detailed enough that a new team member can orient themselves without asking +- **Resources**: add relevant references — design documents (RFC, DACI, PRFAQ), Slack channels, related projects + +You **SHOULD** also set: + +- **Customers**: link relevant customer accounts or support tickets that motivated the work +- **Milestones**: define intermediate delivery milestones for longer projects to track progress incrementally A project without a lead, initiative, or target date **MUST NOT** be moved to **In Progress**. +##### Project Description Template + +The description **SHOULD** follow this structure (copy and fill in): + +```markdown +## Summary + + +## User-facing changes + +- + +## Why are we doing this? + + +## Expected outcomes + +- + +## In scope +- + +## Out of scope + +- + +## Dependencies + + +## Risks + + +## Definition of Done +- [ ] +``` + +See the [Artifact Checklist](#closing-out) below for inspiration on what to include in the Definition of Done. + #### 2. Add Pre-Implementation Documentation Before implementation begins, you **MUST** complete all pre-implementation documentation required by the [Design-First Gate](/sdk/getting-started/standards/planning-scoping#design-first-gate) and [Risk Identification](/sdk/getting-started/standards/planning-scoping#risk-identification) standards. @@ -178,6 +222,37 @@ Run these steps in order when all implementation and documentation is shipped. Verify closure against the [Definition of Done](/sdk/getting-started/standards/planning-scoping#definition-of-done) standard before setting the project to **Done**. +##### Artifact Checklist + +Before closing, verify whether the project requires updates to any of the following. Not every item applies to every project — check the ones relevant to your change: + +- [Sentry Public docs](https://docs.sentry.io/) +- [Sentry Develop Docs](https://develop.sentry.dev) +- [Sentry Conventions](https://getsentry.github.io/sentry-conventions/) +- [Sentry CLI](https://github.com/getsentry/cli) +- [sentry-wizard](https://github.com/getsentry/sentry-wizard) +- Public SDK samples +- In-product prompts/onboarding +- Internal adoption/usage dashboards + +##### Communication Checklist + +For user-facing features, consider whether any of the following are warranted: + +- Write a [Sentry Product Blog](https://blog.sentry.io/) post +- Write a [Sentry Changelog](https://sentry.io/changelog/) entry +- Write a [Sentry Engineering Blog](https://sentry.engineering/blog) post +- Write an [internal blog post](https://vanguard.getsentry.net/) + +##### Follow-Up (if applicable) + +For user-facing features, consider creating a follow-up issue or reminder to: + +- Check how the feature is performing after launch (adoption, error rates, customer feedback) +- Promote the feature to GA (if launching as beta/experimental) + +##### Close-Out Steps + 1. Verify all issues in the project are either **Done** or explicitly **Cancelled** with a note. 2. Post a final update summarizing: what shipped, any known follow-up work, and lessons learned. 3. Set the project status to **Done**. A project **MUST NOT** be set to **Done** if there are open issues that are not yet resolved or intentionally cancelled. diff --git a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx index 4d6b633ea7238..3483c735923ac 100644 --- a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx +++ b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx @@ -71,6 +71,8 @@ Issues estimated larger than **M** (or the team's medium equivalent) **MUST NOT* An issue or project **MUST NOT** be marked done if any of these conditions are unmet. "Mostly done" or "good enough" are not acceptable states — defer remaining work to a follow-up issue or project instead. +For a detailed artifact and communication checklist to verify before closing a project, see [Closing Out](/sdk/getting-started/playbooks/coordination/managing-linear-projects#closing-out). + #### Enforcement - Human review From 52d6f3cb0e352e8a0367d9f5658cb1dd00350b1a Mon Sep 17 00:00:00 2001 From: Chris Aigner <25478494+christophaigner@users.noreply.github.com> Date: Tue, 26 May 2026 16:14:09 +0200 Subject: [PATCH 2/5] Update develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx --- .../playbooks/coordination/managing-linear-projects.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx index 2d4e07fff5347..08a5f5a78a3da 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx @@ -241,7 +241,7 @@ For user-facing features, consider whether any of the following are warranted: - Write a [Sentry Product Blog](https://blog.sentry.io/) post - Write a [Sentry Changelog](https://sentry.io/changelog/) entry -- Write a [Sentry Engineering Blog](https://sentry.engineering/blog) post +- Write a [Sentry Engineering Blog](https://blog.sentry.io/engineering/) post - Write an [internal blog post](https://vanguard.getsentry.net/) ##### Follow-Up (if applicable) From fb0f37961628f7502151629c2016429abe044073 Mon Sep 17 00:00:00 2001 From: Chris Aigner Date: Tue, 26 May 2026 16:19:02 +0200 Subject: [PATCH 3/5] docs(sdk): Remove placeholder bullets from project description template The dash placeholders inside the markdown code block were being rendered as list items on the page, breaking the visual appearance of the template. Co-Authored-By: Claude Co-authored-by: Cursor --- .../playbooks/coordination/managing-linear-projects.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx index 08a5f5a78a3da..f142fda412aed 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx @@ -124,21 +124,17 @@ The description **SHOULD** follow this structure (copy and fill in): ## User-facing changes -- ## Why are we doing this? ## Expected outcomes -- ## In scope -- ## Out of scope -- ## Dependencies From bd507f26421033242da079c8572c53e34d45ebe5 Mon Sep 17 00:00:00 2001 From: Chris Aigner Date: Tue, 26 May 2026 16:21:08 +0200 Subject: [PATCH 4/5] docs(sdk): Move Resources to optional fields and soften SHOULD to should Co-Authored-By: Claude Co-authored-by: Cursor --- .../playbooks/coordination/managing-linear-projects.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx index f142fda412aed..f979afdbcd0be 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx @@ -105,11 +105,11 @@ You **MUST** set all of the following attributes before sharing the project with - **Target date**: realistic delivery date; **MUST** be set before the project moves to **In Progress** - **Team**: the owning SDK team - **Description**: use the structured template below; detailed enough that a new team member can orient themselves without asking -- **Resources**: add relevant references — design documents (RFC, DACI, PRFAQ), Slack channels, related projects -You **SHOULD** also set: +You should also set: - **Customers**: link relevant customer accounts or support tickets that motivated the work +- **Resources**: add relevant references — design documents (RFC, DACI, PRFAQ), Slack channels, related projects - **Milestones**: define intermediate delivery milestones for longer projects to track progress incrementally A project without a lead, initiative, or target date **MUST NOT** be moved to **In Progress**. From ca522291688db65eb615d14ad0d80bf497a3c6ad Mon Sep 17 00:00:00 2001 From: Chris Aigner Date: Tue, 26 May 2026 16:28:33 +0200 Subject: [PATCH 5/5] docs(sdk): Integrate DoD checklist into project description template Move artifact and communication checklists from a separate Closing Out section into the project description template as grouped sub-sections (Have we updated / Have you thought about / follow-up issues). Update the cross-reference in planning-scoping.mdx accordingly. Co-Authored-By: Claude Co-authored-by: Cursor --- .../coordination/managing-linear-projects.mdx | 56 +++++++++---------- .../standards/planning-scoping.mdx | 2 +- 2 files changed, 26 insertions(+), 32 deletions(-) diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx index f979afdbcd0be..0236a46471ac6 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx @@ -143,10 +143,33 @@ The description **SHOULD** follow this structure (copy and fill in): ## Definition of Done + +### Project-specific criteria + - [ ] -``` -See the [Artifact Checklist](#closing-out) below for inspiration on what to include in the Definition of Done. +### Have we updated + +- [ ] [Public docs](https://docs.sentry.io/) +- [ ] [Develop Docs](https://develop.sentry.dev) +- [ ] [Sentry Conventions](https://getsentry.github.io/sentry-conventions/) +- [ ] [Sentry CLI](https://github.com/getsentry/cli) +- [ ] [sentry-wizard](https://github.com/getsentry/sentry-wizard) +- [ ] Public SDK example projects +- [ ] In-product prompts/onboarding +- [ ] Internal adoption/usage dashboards + +### Have you thought about doing a/an +- [ ] [Sentry Product Blog](https://blog.sentry.io/) post +- [ ] [Sentry Changelog](https://sentry.io/changelog/) entry +- [ ] [Sentry Engineering Blog](https://sentry.engineering/blog) post +- [ ] [internal blog post](https://vanguard.getsentry.net/) +- [ ] S&T video + +### Don't forget to create a follow-up issue to +- [ ] Check how the feature is performing after launch +- [ ] Promote the feature to GA +``` #### 2. Add Pre-Implementation Documentation @@ -218,35 +241,6 @@ Run these steps in order when all implementation and documentation is shipped. Verify closure against the [Definition of Done](/sdk/getting-started/standards/planning-scoping#definition-of-done) standard before setting the project to **Done**. -##### Artifact Checklist - -Before closing, verify whether the project requires updates to any of the following. Not every item applies to every project — check the ones relevant to your change: - -- [Sentry Public docs](https://docs.sentry.io/) -- [Sentry Develop Docs](https://develop.sentry.dev) -- [Sentry Conventions](https://getsentry.github.io/sentry-conventions/) -- [Sentry CLI](https://github.com/getsentry/cli) -- [sentry-wizard](https://github.com/getsentry/sentry-wizard) -- Public SDK samples -- In-product prompts/onboarding -- Internal adoption/usage dashboards - -##### Communication Checklist - -For user-facing features, consider whether any of the following are warranted: - -- Write a [Sentry Product Blog](https://blog.sentry.io/) post -- Write a [Sentry Changelog](https://sentry.io/changelog/) entry -- Write a [Sentry Engineering Blog](https://blog.sentry.io/engineering/) post -- Write an [internal blog post](https://vanguard.getsentry.net/) - -##### Follow-Up (if applicable) - -For user-facing features, consider creating a follow-up issue or reminder to: - -- Check how the feature is performing after launch (adoption, error rates, customer feedback) -- Promote the feature to GA (if launching as beta/experimental) - ##### Close-Out Steps 1. Verify all issues in the project are either **Done** or explicitly **Cancelled** with a note. diff --git a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx index 3483c735923ac..b49a4448740ae 100644 --- a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx +++ b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx @@ -71,7 +71,7 @@ Issues estimated larger than **M** (or the team's medium equivalent) **MUST NOT* An issue or project **MUST NOT** be marked done if any of these conditions are unmet. "Mostly done" or "good enough" are not acceptable states — defer remaining work to a follow-up issue or project instead. -For a detailed artifact and communication checklist to verify before closing a project, see [Closing Out](/sdk/getting-started/playbooks/coordination/managing-linear-projects#closing-out). +For a project description template including an artifact and communication checklist for the Definition of Done, see [Project Description Template](/sdk/getting-started/playbooks/coordination/managing-linear-projects#project-description-template). #### Enforcement