Skip to content

Commit 448526a

Browse files
dsp-antdsp-ant
committed
shorten the language
1 parent a11b155 commit 448526a

3 files changed

Lines changed: 45 additions & 163 deletions

File tree

‎docs/community/feature-lifecycle.mdx‎

Lines changed: 39 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@ description: How individual MCP specification features move through Active, Depr
44
---
55

66
This policy defines a lifecycle for individual features within the Model
7-
Context Protocol specification, separate from the revision lifecycle of the
8-
specification document itself. It introduces three feature states (Active,
7+
Context Protocol specification. It defines three feature states (Active,
98
Deprecated, Removed), the criteria and procedure for moving between them, a
109
minimum window between deprecation and removal, and the documentation required
1110
at each transition.
@@ -17,34 +16,18 @@ This policy was adopted via
1716

1817
This policy governs **features** of the MCP core specification: protocol
1918
messages, capabilities, transports, schema types, and normative behavioral
20-
requirements. It does not govern the independent lifecycle of SDK-specific
21-
APIs, registry policies, or the revision lifecycle of the specification
22-
document itself (Draft, Current, Final), which is defined in the
23-
[versioning guide](/docs/learn/versioning).
24-
25-
Note that "Final" is used in two senses in this document: a specification
26-
_revision_ is Final when superseded by a later one (per the versioning guide),
27-
and a _SEP_ reaches Final when its status advances per the
28-
[SEP guidelines](/community/sep-guidelines). Context disambiguates; where it
29-
does not, this document writes "the SEP reaches Final" or "Final revision"
30-
explicitly.
19+
requirements. Tthe revision lifecycle of the specification document itself
20+
(Draft, Current, Final), is defined in the [versioning guide](/docs/learn/versioning).
3121

3222
## Feature States
3323

3424
A specification feature is in exactly one of three states:
3525

3626
| State | Meaning | Implementer expectation |
3727
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
38-
| **Active** | The feature is part of the Current specification revision with no planned removal. | Implement per the feature's normative requirements. |
39-
| **Deprecated** | The feature remains in the specification but is scheduled for removal. A migration path is documented (see below). | New implementations SHOULD NOT adopt the feature. Existing implementations SHOULD migrate before the earliest removal date. |
40-
| **Removed** | The feature has been deleted from `draft` and will be absent from the next Current revision. It remains documented in the Final revision it last appeared in. | Implementations targeting that next Current revision MUST NOT depend on the feature. |
41-
42-
The term "soft-deprecated" is retired. Existing uses in the specification are
43-
reclassified as Deprecated under this policy (see [Transition](#transition)).
44-
45-
Removal from the specification does not oblige an SDK to drop the feature from
46-
releases that continue to support an earlier revision in which it was Active or
47-
Deprecated; that timeline is governed by the SDK's own revision-support policy.
28+
| **Active** | The feature is part of the Current specification revision. | Implement per the feature's normative requirements. |
29+
| **Deprecated** | The feature remains in the specification but is scheduled for removal. A migration path is documented (see below). | New implementations should not adopt the feature. Existing implementations should migrate before the earliest removal date. |
30+
| **Removed** | The feature has been deleted from `draft` and will be absent from the next Current revision. It remains documented in the Final revision it last appeared in. | Implementations targeting that next Current revision must not depend on the feature. |
4831

4932
A Deprecated feature MAY be restored to Active by a SEP that supersedes the
5033
deprecation SEP and documents the changed circumstances. Restoration follows
@@ -53,45 +36,40 @@ again, the minimum deprecation window in
5336
[Deprecating a feature](#deprecating-a-feature) is measured afresh from the
5437
revision in which the new deprecation takes effect.
5538

56-
## Deprecating a Feature
39+
### SDKs
40+
Removal from the specification does not oblige an SDK to drop the feature from
41+
releases. That timeline is governed by the SDK's own revision-support policy.
42+
5743

58-
A feature MAY be proposed for deprecation when at least one of the following
59-
holds:
44+
## Deprecating a Feature
45+
A feature may be proposed for deprecation due to
6046

61-
- It has been superseded by another feature that covers the same use cases.
62-
- It presents a security, privacy, or interoperability risk that cannot be
63-
mitigated in place.
64-
- Ecosystem telemetry or SDK maintainer consensus indicates negligible adoption
65-
relative to its maintenance cost.
47+
- it has been superseded by another feature that covers the same use cases,
48+
- it presents a security, privacy, or interoperability risk that cannot be
49+
mitigated in place,
50+
- ecosystem telemetry or SDK maintainer consensus indicates negligible adoption
51+
relative to its maintenance cost,
52+
- or any other reasons the Core Maintainers seem to deem appropriate.
6653

6754
Deprecation is a specification change and therefore requires a SEP per the
68-
[SEP guidelines](/community/sep-guidelines). The deprecation SEP MUST:
55+
[SEP guidelines](/community/sep-guidelines). The deprecation SEP must:
6956

7057
1. Identify the feature by name and link to its definition in `schema.ts`
7158
(where applicable) and the specification prose.
7259
2. State the rationale against the criteria above.
7360
3. Document the migration path, or state explicitly that none is required. If
74-
the migration path names a replacement feature, that feature MUST be Active
61+
the migration path names a replacement feature, that feature must be Active
7562
in the revision in which the deprecation takes effect; the replacement and
76-
the deprecation MAY land in the same revision. A feature is not deprecated
77-
under this policy while its documented replacement is still only in `draft`.
63+
the deprecation may land in the same revision.
7864
4. Specify the **minimum deprecation window**: the number of months, at least
79-
twelve, that the feature MUST remain Deprecated before it is eligible for
65+
twelve, that the feature must remain Deprecated before it is eligible for
8066
removal. The window is measured from the release of the specification
8167
revision in which the feature is first marked Deprecated, not from the date
8268
the SEP reaches Final. The feature becomes eligible for removal in the first
8369
specification revision released as Current on or after the window elapses;
8470
that point is the feature's **earliest removal**.
8571

86-
When the deprecation SEP reaches Final the deprecation is scheduled: the
87-
following changes land in the draft specification (`schema/draft/` and
88-
`docs/specification/draft/`). The feature becomes Deprecated when the revision
89-
carrying these changes is released as Current under the
90-
[versioning guide](/docs/learn/versioning), and the minimum deprecation window
91-
is counted from that release. Anchoring the clock to the revision release means
92-
every feature deprecated in the same revision shares one earliest removal
93-
rather than each carrying a date derived from when its own SEP happened to
94-
land.
72+
When the deprecation SEP is accepted and reaches Final, the deprecation is scheduled.
9573

9674
- The feature's entry in `schema.ts` gains a `@deprecated` JSDoc tag
9775
referencing the deprecation SEP and the revision in which the deprecation
@@ -106,139 +84,51 @@ land.
10684
revision in which it became Deprecated, its migration path, and its earliest
10785
removal.
10886

87+
The feature becomes Deprecated when the revision carrying these changes is released
88+
and becomes the new Current revision (see [versioning guide](/docs/learn/versioning)).
89+
The minimum deprecation window is counted from that release.
90+
10991
## The Deprecated Registry
11092

11193
[`docs/specification/draft/deprecated.mdx`](/specification/draft/deprecated) is
112-
a single page listing every feature currently in the Deprecated state. It is
94+
a single page listing every feature Deprecated or Removed state. It is
11395
the canonical answer to "what is on its way out, and by when," so that an
11496
implementer does not have to reconstruct that picture from deprecation entries
115-
spread across revision changelogs. Each row records the feature, its
116-
deprecation SEP, the revision in which it became Deprecated, the documented
117-
migration path, and its earliest removal. A deprecation adds a row; a removal
118-
moves the row to a Removed section of the same page with a link to the
119-
changelog entry, so the page also serves as the historical record. The registry
120-
carries no normative force of its own; it is a derived view kept consistent
121-
with the per-feature notices and changelog entries, which are the normative
122-
records.
97+
spread across revision changelogs.
12398

12499
## Tier 1 SDK Obligations
125100

126-
A feature lifecycle is only as effective as the implementations that surface it
127-
to consumers. The specification artifacts above record that a feature is
128-
Deprecated; Tier 1 SDKs (per the [SDK tiering system](/community/sdk-tiers))
129-
deliver that record to the implementers who would otherwise discover the
130-
removal by breakage. Once the revision in which a feature becomes Deprecated is
101+
Once the revision in which a feature becomes Deprecated is
131102
released as Current, Tier 1 SDKs:
132103

133-
- MUST mark the corresponding API surface deprecated using the language's
104+
- Must mark the corresponding API surface deprecated using the language's
134105
native mechanism (for example `@Deprecated` in Java, `[Obsolete]` in .NET,
135106
`@deprecated` JSDoc in TypeScript, the `Deprecated:` doc convention in Go) in
136107
their next release, referencing the deprecation SEP and the earliest removal
137-
date where the mechanism permits. The marker applies to the SDK API surface
138-
and is not conditioned on the specification revision a consumer targets;
139-
surfacing it to consumers still on an earlier revision is intentional forward
140-
signal.
141-
- SHOULD emit a runtime warning when a deprecated feature is exercised, using
108+
date where the mechanism permits.
109+
- Should emit a runtime warning when a deprecated feature is exercised, using
142110
the language's idiomatic mechanism (for example Python's
143111
`DeprecationWarning`, Node.js's `process.emitWarning`, or a configurable
144-
logger). A runtime warning reaches developers who never read API
145-
documentation and is an observable signal a conformance test can assert
146-
against.
147-
148-
These obligations are conformance criteria for Tier 1 status. A Tier 1 SDK that
149-
persistently fails to surface a Deprecated feature is subject to the
150-
[Tier Relegation Process](/community/sdk-tiers#tier-relegation).
112+
logger).
151113

152114
## Removing a Feature
153115

154116
1. Once a feature is set for removal, the removal is executed at the discretion
155-
of the Core Maintainers after the minimum deprecation window has elapsed,
156-
during release preparation, under the
157-
[governance decision process](/community/governance#decision-process).
158-
Removal does not require its own SEP. Before removing a feature the Core
159-
Maintainers MUST confirm that the migration target named in the deprecation
160-
SEP, if any, is still Active.
161-
2. A SEP is required for any other change to a deprecation or removal, for
117+
of the Core Maintainers after the minimum deprecation window has elapsed.
118+
2. The removal needs to be documented in the `changelog.mdx` and [registry](#the-deprecated-regsitry)
119+
2. A SEP is required for any change to the original deprecation or removal SEP, for
162120
example extending or shortening the timeline
163121
([Expedited removal](#expedited-removal)) or restoring the feature to Active
164122
([Feature states](#feature-states)).
165123

166-
Note that features may remain Deprecated, without removal, for much longer than
167-
the minimum deprecation window.
168-
169-
SDKs implement deprecation as part of the
170-
[SDK tiering system](/community/sdk-tiers) (see
171-
[Tier 1 SDK obligations](#tier-1-sdk-obligations)); removal imposes no
172-
additional requirements on SDK maintainers.
173-
174-
When a removal decision is taken, the feature is deleted from
175-
`schema/draft/schema.ts` (where present) and the draft specification prose;
176-
`changelog.mdx` for that revision gains an entry under the "Removed" heading
177-
that links to the deprecation SEP and the last Final revision in which the
178-
feature was present; and the feature's [registry](#the-deprecated-registry) row
179-
moves to the Removed section with a link to that changelog entry.
180-
181124
## Expedited Removal
182125

183-
The twelve-month floor MAY be shortened when the feature presents an active
126+
The twelve-month floor may be shortened when the feature presents an active
184127
security risk, meaning a vulnerability with a published security advisory or
185128
documented in-the-wild exploitation for which no in-place mitigation exists.
186129
Shortening the window requires Core Maintainer approval under the
187130
[governance decision process](/community/governance#decision-process), recorded
188131
in the deprecation SEP or, where the risk surfaces after that SEP is already
189132
Final, in a short expedited-removal SEP that references it. The shortened
190-
window MUST still provide at least ninety days between the feature becoming
133+
window must still provide at least ninety days between the feature becoming
191134
Deprecated and its earliest removal.
192-
193-
## Roles
194-
195-
| Action | Who |
196-
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
197-
| Propose deprecation, extension, or restoration | Any contributor, per the SEP process |
198-
| Sponsor | A Maintainer or Core Maintainer, per the SEP process |
199-
| Approve a deprecation SEP | Core Maintainers, per the [governance decision process](/community/governance#decision-process) |
200-
| Decide a removal during release preparation | Core Maintainers, per the [governance decision process](/community/governance#decision-process) |
201-
| Approve an extension or restoration SEP | Core Maintainers, per the [governance decision process](/community/governance#decision-process) |
202-
| Approve expedited removal | Core Maintainers, per the [governance decision process](/community/governance#decision-process) |
203-
204-
As with all Core Maintainer decisions, Lead Maintainers retain veto authority
205-
over each of the approvals above, per the
206-
[governance roles](/community/governance#roles) definition.
207-
208-
## Transition
209-
210-
Two features were already described as deprecated in the specification before
211-
this policy existed. They are classified as Deprecated and seeded into the
212-
[registry](#the-deprecated-registry); the deprecation-SEP requirements in
213-
[Deprecating a feature](#deprecating-a-feature) are not applied retroactively.
214-
The deprecation decision in each case predates this policy; this section
215-
records it under the new vocabulary so the terms "deprecated" and
216-
"soft-deprecated" carry a single defined meaning going forward.
217-
218-
The HTTP+SSE transport was publicly deprecated well over twelve months before
219-
this policy was adopted, so the minimum deprecation window has in practice
220-
already been served; re-anchoring its clock to a future revision release would
221-
restart a window the ecosystem has already had. It is therefore given a
222-
three-month grace period from the date SEP-2596 reached Final before it is
223-
eligible for removal, matching the floor the
224-
[Expedited removal](#expedited-removal) clause sets for the shortest
225-
permissible window. Removal still follows
226-
[Removing a feature](#removing-a-feature): a Core Maintainer decision at
227-
release preparation, not an automatic event when the grace period ends.
228-
229-
| Feature | Migration target | Earliest removal |
230-
| ----------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
231-
| HTTP+SSE transport | [Streamable HTTP](/specification/draft/basic/transports#streamable-http) | Three months after SEP-2596 is Final |
232-
| `includeContext: "thisServer"` / `"allServers"` | Omit the field or use `"none"` | Follows Sampling ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)) |
233-
234-
`includeContext` is a parameter of `sampling/createMessage`.
235-
[SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)
236-
deprecates the Sampling feature as a whole; the two affected `includeContext`
237-
values follow that feature's deprecation schedule rather than carrying an
238-
independent removal clock, and are removed no later than Sampling itself.
239-
240-
This grandfathering applies only to features the specification already
241-
described as deprecated on the date SEP-2596 reached Final. Every subsequent
242-
deprecation follows [Deprecating a feature](#deprecating-a-feature) in full,
243-
and removal of the grandfathered features follows
244-
[Removing a feature](#removing-a-feature) without exception.

‎docs/docs/learn/versioning.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,10 @@ Individual features of the specification may additionally be marked as
3333
[feature lifecycle and deprecation policy](/community/feature-lifecycle):
3434
the feature remains part of the specification, but is scheduled for removal.
3535
Deprecated features document a migration path (or state that none is required)
36-
and remain in the specification for at least twelve months — or at least
36+
and remain in the specification for at least twelve months, or at least
3737
ninety days under the policy's
3838
[expedited-removal exception](/community/feature-lifecycle#expedited-removal)
39-
— before they become eligible for removal, after which they may be **Removed**
39+
, before they become eligible for removal, after which they may be **Removed**
4040
in a future revision.
4141

4242
Features that are currently Deprecated are listed in the

0 commit comments

Comments
 (0)