docs(sdk): Rewrite Coordination/Maintenance and Release/Versioning specs#17020
Merged
stephanie-anderson merged 6 commits intomasterfrom Mar 18, 2026
Merged
Conversation
Replace rigid Rule/Enforcement/Per-SDK override template with natural prose across both pages. Merge related sections, remove enforcement boilerplate and StatusBadge components, and promote spec status to stable. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Comment on lines
99
to
107
|
|
||
| - Human process | ||
| ## Documenting decisions | ||
|
|
||
| #### Per-SDK override | ||
| Decisions should be traceable. Before making one, reference or create a Linear or GitHub issue to anchor the discussion. If a meeting happens, enable notes or recording — key decisions **MUST** be summarized and linked to the issue afterward. | ||
|
|
||
| <StatusBadge type="no" /> Applies universally. | ||
| Slack is fine for coordination, but outcomes **MUST** be moved to the system of record (Linear, GitHub, or Develop Docs) before the thread is considered closed. Update the issue immediately, link supporting docs, and assign action items with owners. | ||
|
|
||
| </SpecSection> | ||
|
|
There was a problem hiding this comment.
Bug: Refactoring coordination-maintenance.mdx broke inbound links from at least five other documentation files because the corresponding anchor links were not updated.
Severity: CRITICAL
Suggested Fix
Update the anchor links in all affected files to point to the new, correct section IDs. For example, links to #post-release-monitoring and #rollback-procedures should now point to the new #releases section. Similarly, update links for #triaging-sla, #waiting-for-labels, and #platformlanguage-version-support-policy to their new targets.
Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.
Location:
develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx#L99-L107
Potential issue: Refactoring in `coordination-maintenance.mdx` involved removing or
renaming several sections, including `#post-release-monitoring`, `#rollback-procedures`,
`#triaging-sla`, and `#waiting-for-labels`. The section ID for `version-support-policy`
was also changed. However, multiple other documentation files were not updated to
reflect these changes. Files like `handling-a-regression.mdx`, `cutting-a-release.mdx`,
`triaging.mdx`, and `dropping-platform-support.mdx` still contain links pointing to
these old, non-existent anchors. This will result in broken links and 404 errors for
users navigating the documentation.
Did we get this right? 👍 / 👎 to inform future reviews.
| ## Platform and language version support | ||
|
|
||
| - Automated labeling via GitHub Actions and Linear automation | ||
| Supported versions should be documented in the README and docs. Dropping support for a platform or language version is a breaking change — it follows the [breaking change and deprecation process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) and needs evidence: usage data, upstream EOL status, or maintenance burden. Announce it at least one minor release before the major that drops support. |
There was a problem hiding this comment.
Bug: A new link in coordination-maintenance.mdx points to a non-existent anchor, #breaking-and-deprecation, in the api-architecture.mdx file, creating a broken link.
Severity: CRITICAL
Suggested Fix
Update the link in coordination-maintenance.mdx to point to a valid anchor. Either link to one of the existing sections like #breaking-change-process or #deprecation-lifecycle, or update the target file api-architecture.mdx to include an anchor with the ID breaking-and-deprecation.
Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.
Location: develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx#L62
Potential issue: A new link was added in `coordination-maintenance.mdx` that points to a
non-existent anchor. The link `[breaking change and deprecation
process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation)`
targets an anchor `#breaking-and-deprecation` within `api-architecture.mdx`. However,
the target file does not contain a section with this ID. Instead, it has separate
sections with IDs `breaking-change-process` and `deprecation-lifecycle`. This will cause
the link to fail to navigate to the correct part of the page.
Did we get this right? 👍 / 👎 to inform future reviews.
…egression handling" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ase-versioning Update playbook links to match new section IDs after spec rewrite. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
dingsdax
approved these changes
Mar 18, 2026
stephanie-anderson
deleted the
docs/humanize-coordination-maintenance-spec
branch
stephanie-anderson
added a commit
that referenced
this pull request
Mar 18, 2026
…ecs (#17020) Rewrites both standards pages to be more human-friendly: **Coordination and Maintenance:** - Add intro paragraph - Merge triaging SLA and waiting-for labels into one "Issue triage" section - Merge post-release monitoring and rollback into "Post-release monitoring and regression handling", reframe rollback as regression handling **Release and Versioning:** - Add intro paragraph - Merge version format, pre-release identifiers, and build identifiers into one "Versioning" section - Merge release tooling, merge target, and multiple craft configs into one "Release tooling" section - Add cross-reference to post-release monitoring **Both pages:** - Replace rigid Rule/Enforcement/Per-SDK override template with natural prose - Remove enforcement boilerplate, StatusBadge components, and suggested skills - Promote spec status to stable --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Johannes Daxböck <johannes.daxboeck@sentry.io>
constantinius
pushed a commit
that referenced
this pull request
Mar 20, 2026
…ecs (#17020) Rewrites both standards pages to be more human-friendly: **Coordination and Maintenance:** - Add intro paragraph - Merge triaging SLA and waiting-for labels into one "Issue triage" section - Merge post-release monitoring and rollback into "Post-release monitoring and regression handling", reframe rollback as regression handling **Release and Versioning:** - Add intro paragraph - Merge version format, pre-release identifiers, and build identifiers into one "Versioning" section - Merge release tooling, merge target, and multiple craft configs into one "Release tooling" section - Add cross-reference to post-release monitoring **Both pages:** - Replace rigid Rule/Enforcement/Per-SDK override template with natural prose - Remove enforcement boilerplate, StatusBadge components, and suggested skills - Promote spec status to stable --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Johannes Daxböck <johannes.daxboeck@sentry.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites both standards pages to be more human-friendly:
Coordination and Maintenance:
Release and Versioning:
Both pages: