Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC4209: Updating endpoints in-place #4209

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

MSC4209: Updating endpoints in-place #4209

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions proposals/4209-updating-endpoints-in-place.md
View file
Open in desktop
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation requirements:

  • None? This is a policy clarification.

Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# MSC4209: Updating endpoints in-place

The current [deprecation policy](https://spec.matrix.org/v1.11/#deprecation-policy) does not clarify
how the specification should address endpoints being updated in a backwards incompatible manner. When
a breaking change is made to an endpoint, that endpoint's version is increased, however the old endpoint
may still exist on some server implementations. The deprecation policy can be read to mean that both
old and new endpoint must exist in the spec for at least 1 version, however this can add confusion
when attempting to implement the specification.

This proposal covers an alternative arrangement, where endpoints simply experiencing a version increase
are not required to maintain the old endpoint as deprecated. The deprecation is instead implied by
the version change. Servers which advertise support for old specification versions are still required
to implement both old and new endpoint.

This proposal does not apply to situations where the endpoint changes namespace, path structure, etc.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the reasoning behind limiting in-place updates without deprecation to version changes in the path? Could these not involve drastic behavioral changes of the endpoint's behavior similar to the excluded situations listed here?


## Proposal

When an MSC makes a breaking change to an endpoint such that the version is increased, the old endpoint
is automatically deprecated and can be removed from the specification. This is to be codified in the
[deprecation policy](https://spec.matrix.org/v1.11/#deprecation-policy).

There may be situations where explicitly listing the old endpoint as deprecated in the specification
is preferred. This is supported by this policy clarification, and left to the discretion of the Spec
Core Team (SCT) during PR review.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since removal without deprecation is the intended default case, maybe it'd be better to formulate this as the old endpoint being automatically removed and the SCT having discretion to mandate deprecation? The current wording "automatically deprecated and can be removed" left me slightly confused in the beginning because if it's removed, it's no longer deprecated.


Servers which implement multiple versions of the specification are still required to implement all
endpoints, regardless of per-endpoint versioning, described by those specification versions. For example,
if Matrix 1.1 has `/v1/test` and Matrix 1.2 replaces it with `/v2/test`, a server supporting both 1.1
and 1.2 would be required to implement both endpoints. A server only supporting 1.2 would only need
to support the `/v2` endpoint.

## Potential issues

No major issues are foreseen.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This proposal will result in the spec listing a single situation in which deprecation can be skipped. This in turn implies that deprecation is mandatory for all other breaking changes. Is this intended?


## Alternatives

There are no significant alternatives.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not significant but instead of listing situations that are exempt from deprecation, we could also list situations that require deprecation.


## Security considerations

This proposal does not materially affect the security profile of the protocol.

## Unstable prefix

This proposal does not implementation criteria which require an unstable prefix.

## Dependencies

There are no direct dependencies for this proposal.