docs(sdk): Add Linear project description template by christophaigner · Pull Request #17861 · getsentry/sentry-docs

christophaigner · 2026-05-22T08:25:11Z

DESCRIBE YOUR PR

Preview is here.

Expands the Managing Linear Projects playbook with more prescriptive guidance on project setup and close-out.

Changes:

Project fields: split into MUST (title, initiative, lead, status, target date, team, description, resources) / SHOULD (customers, milestones)
Project description template: replaced the prose description with a copyable markdown template with inline comment prompts (summary, customer-facing changes, why, expected outcomes, in/out of scope, dependencies, risks, DoD)
Closing Out — Artifact Checklist: bullet list of artifacts to verify before closing (public docs, develop docs, sentry-conventions, sentry-wizard, Sentry CLI, public samples, in-product prompts, dashboards)
Closing Out — Communication Checklist: marketing, Vanguard, blog posts, changelog
Closing Out — Follow-Up: post-launch performance check and GA promotion (scoped to user-facing features)
planning-scoping.mdx: added a cross-reference from the project-level DoD to the new artifact checklist

Once merged, we can also add a Linear project template for it.

IS YOUR CHANGE URGENT?

None: Not urgent, can wait up to 1 week+

PRE-MERGE CHECKLIST

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team

Made with Cursor

…book 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 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

vercel · 2026-05-22T08:25:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview, Comment	Jun 2, 2026 8:40am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ignored	Preview	Jun 2, 2026 8:40am

…e-improvements

…ng-linear-projects.mdx

…e-improvements

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 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

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 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

…e-improvements

Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

dingsdax · 2026-06-01T09:32:35Z

+- [ ] In-product prompts/onboarding
+- [ ] Internal adoption/usage dashboards
+
+### Have you thought about doing a


this could also be automated ... once checked here ... create a Linear issue for it

Definitely, we can have a look at this in a follow-up then 👍🏻

Summary is a dedicated field in Linear (below the title), so it belongs in the required attributes list rather than inside the description template. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

dingsdax · 2026-06-01T11:58:32Z

another thing that came to my mind, is that for almost all SDK alignment projects ... the template also applies to the initiative and we usually just point to the initiative description, assets b/c the per SDK differences are mostly minimal

coolguyzone

LGTM!

Co-authored-by: Alex Krawiec <alexanderkrawiec@gmail.com>

For projects under a shared initiative, the per-SDK description can reference the initiative and only document SDK-specific deviations. Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

christophaigner · 2026-06-02T08:35:36Z

another thing that came to my mind, is that for almost all SDK alignment projects ... the template also applies to the initiative and we usually just point to the initiative description, assets b/c the per SDK differences are mostly minimal

@dingsdax agreed, what do you think about 0b5cf4e?

dingsdax · 2026-06-02T08:42:23Z

nice 👍

mujacica · 2026-06-02T14:22:32Z

+
+- **Customers**: link relevant customer accounts or support tickets that motivated the work
+- **Resources**: add relevant references (especially for larger initiatives) — design documents ([RFC](https://github.com/getsentry/rfcs), DACI, PRFAQ), Slack channels, related projects, and so on
+- **Milestones**: define intermediate delivery milestones for longer projects to track progress incrementally


Maybe also linking to existing/creating new initiatives if required?

mujacica · 2026-06-02T14:26:00Z

+Use this template as a starting point for the project description. For cross-SDK rollout projects where the initiative already covers the shared context (motivation, scope, outcomes), the per-SDK project description can reference the initiative and only document SDK-specific deviations (e.g., different scope, additional risks, platform-specific dependencies).
+
+```markdown
+## Why are we doing this?


Including customer signals/anecdotes is usually what helps me understand the issues the best. Could be a smaller comment/addition here.

mujacica · 2026-06-02T14:26:44Z

+## Risks
+<!-- What's most likely to go wrong? What's the mitigation? -->
+
+## Definition of Done


Do we want to template this, or allow every project to define their own definition of done - e.g. closed issues, deployed, tested etc?

Looking at the section below it looks like there is already a section for project-specific ones?

github-actions Bot added the sdk-develop-docs PRs touching develop-docs/sdk label May 22, 2026

vercel Bot deployed to Preview – develop-docs May 22, 2026 08:29 View deployment

Merge branch 'master' into christophaigner/docs/project-issue-templat…

7bab4d1

…e-improvements

vercel Bot deployed to Preview – develop-docs May 22, 2026 09:44 View deployment

vercel Bot deployed to Preview – sentry-docs May 22, 2026 09:53 View deployment

christophaigner commented May 26, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

christophaigner commented May 26, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

christophaigner commented May 26, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

christophaigner and others added 5 commits May 26, 2026 16:14

Update develop-docs/sdk/getting-started/playbooks/coordination/managi…

52d6f3c

…ng-linear-projects.mdx

Merge branch 'master' into christophaigner/docs/project-issue-templat…

a19b662

…e-improvements

docs(sdk): Move Resources to optional fields and soften SHOULD to should

bd507f2

Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview – develop-docs May 26, 2026 14:28 View deployment

vercel Bot deployed to Preview – develop-docs May 26, 2026 14:34 View deployment

Merge branch 'master' into christophaigner/docs/project-issue-templat…

94cfef9

…e-improvements

vercel Bot deployed to Preview – develop-docs June 1, 2026 08:23 View deployment

vercel Bot deployed to Preview – sentry-docs June 1, 2026 08:28 View deployment

docs(sdk): Add in-scope comment, RFC link, and minor template tweaks

8302714

Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

vercel Bot deployed to Preview – develop-docs June 1, 2026 08:37 View deployment

christophaigner and others added 2 commits June 1, 2026 11:24

docs(sdk): Refine project description template wording

a977e40

Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

docs(sdk): Rephrase project description template intro

c960a79

Co-Authored-By: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

christophaigner requested review from dingsdax, mujacica and stephanie-anderson June 1, 2026 09:26

christophaigner marked this pull request as ready for review June 1, 2026 09:26

christophaigner changed the title ~~docs(sdk): Expand project setup and close-out guidance in Linear playbook~~ docs(sdk): Add Linear project description template Jun 1, 2026

christophaigner requested a review from mydea June 1, 2026 09:27

dingsdax reviewed Jun 1, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

vercel Bot deployed to Preview – develop-docs June 1, 2026 09:31 View deployment

dingsdax reviewed Jun 1, 2026

View reviewed changes

dingsdax approved these changes Jun 1, 2026

View reviewed changes

sentry Bot reviewed Jun 1, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx

vercel Bot deployed to Preview – develop-docs June 1, 2026 09:43 View deployment

christophaigner commented Jun 1, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

Apply suggestion from @christophaigner

0cfed2a

vercel Bot deployed to Preview – develop-docs June 1, 2026 09:56 View deployment

coolguyzone reviewed Jun 1, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

coolguyzone reviewed Jun 1, 2026

View reviewed changes

Comment thread develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx Outdated

coolguyzone approved these changes Jun 1, 2026

View reviewed changes

Apply suggestions from code review

0d804df

Co-authored-by: Alex Krawiec <alexanderkrawiec@gmail.com>

vercel Bot deployed to Preview – develop-docs June 2, 2026 08:29 View deployment

vercel Bot deployed to Preview – develop-docs June 2, 2026 08:40 View deployment

mujacica reviewed Jun 2, 2026

View reviewed changes

Uh oh!

Conversation

christophaigner commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

PRE-MERGE CHECKLIST

Uh oh!

vercel Bot commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dingsdax Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

christophaigner Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dingsdax commented Jun 1, 2026

Uh oh!

Uh oh!

Uh oh!

coolguyzone left a comment

Choose a reason for hiding this comment

Uh oh!

christophaigner commented Jun 2, 2026

Uh oh!

dingsdax commented Jun 2, 2026

Uh oh!

mujacica Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

mujacica Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

mujacica Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

mujacica Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

christophaigner commented May 22, 2026 •

edited

Loading

vercel Bot commented May 22, 2026 •

edited

Loading