mirror of
https://github.com/dart-lang/sdk
synced 2024-09-16 02:17:14 +00:00
Create breaking-changes.md
Closes #35403 https://github.com/dart-lang/sdk/pull/35403 GitOrigin-RevId: cbf8ab36ee9e5c955405f6a7b716f4030c87a6ef Change-Id: I024bd034ab34c92535489b97d66e8680c168f430 Reviewed-on: https://dart-review.googlesource.com/c/87168 Commit-Queue: Michael Thomsen <mit@google.com> Reviewed-by: Kevin Moore <kevmoo@google.com>
This commit is contained in:
parent
6dfb3e9f60
commit
37e06d34b2
155
docs/process/breaking-changes.md
Normal file
155
docs/process/breaking-changes.md
Normal file
|
@ -0,0 +1,155 @@
|
||||||
|
# Dart SDK breaking change process
|
||||||
|
|
||||||
|
The present document describes the Dart SDK philosophy for compatibility, and
|
||||||
|
process for breaking changes.
|
||||||
|
|
||||||
|
## Dart compatibility and philosophy
|
||||||
|
|
||||||
|
Generally the Dart team strives to not make breaking changes, and to preserve
|
||||||
|
compatibility of all Dart programs across stable Dart SDK releases. However, on
|
||||||
|
occasion, we believe that breaking changes are needed, or justified:
|
||||||
|
|
||||||
|
* Security: To resolve a security issue in the specification or implementation.
|
||||||
|
|
||||||
|
* Unspecified behavior: Programs that depend on unspecified behavior may break
|
||||||
|
as such behavior is specified and implemented.
|
||||||
|
|
||||||
|
* Implementation bugs: If the implementation deviates unintentionally from the
|
||||||
|
specification, programs may break as we rectify the implementation.
|
||||||
|
|
||||||
|
* Evolution: If we deem that there is a very large benefit to changing current
|
||||||
|
behavior, we may choose to do so after careful consideration of the associated
|
||||||
|
impact of the change.
|
||||||
|
|
||||||
|
## Scope of compatibility
|
||||||
|
|
||||||
|
It is not practical to offer compatability to programs that do not follow
|
||||||
|
best practices. Thus, the breaking change process assumes that programs
|
||||||
|
abide by the following basic conditions:
|
||||||
|
|
||||||
|
* Must contain no static analysis **errors**.
|
||||||
|
|
||||||
|
* Must not rely on a certain runtime **error** being thrown (in other words,
|
||||||
|
a new SDK might throw fewer errors than an old SDK).
|
||||||
|
|
||||||
|
* Must access libraries via the public API (for example, must not reach into
|
||||||
|
the internals of a package located in the `/src/` directory).
|
||||||
|
|
||||||
|
* Must not rely on an [experiment flag](flags.md).
|
||||||
|
|
||||||
|
* Must not circumvent clear restrictions documented in the public API
|
||||||
|
documentation (for example, must not mixin a class clearly documented as
|
||||||
|
not intended to be used as a mixin).
|
||||||
|
|
||||||
|
Compatibility is only considered between stable releases (i.e. releases from the
|
||||||
|
[Dart stable
|
||||||
|
channel](https://www.dartlang.org/tools/sdk/archive#stable-channel)).
|
||||||
|
|
||||||
|
## Breaking change notification
|
||||||
|
|
||||||
|
Anyone wishing to make a breaking change to Dart is expected to perform the
|
||||||
|
following steps. It is expected that all of these steps are followed prior
|
||||||
|
to a change being released in a dev channel release.
|
||||||
|
|
||||||
|
### Step 1: Announcement
|
||||||
|
|
||||||
|
* Create an issue in the Dart SDK issue tracker labelled
|
||||||
|
`breaking-change-request` containing the following:
|
||||||
|
|
||||||
|
* The intended change in behavior.
|
||||||
|
|
||||||
|
* The justification/rationale for making the change.
|
||||||
|
|
||||||
|
* The expected impact of this change.
|
||||||
|
|
||||||
|
* Clear steps for mitigating the change.
|
||||||
|
|
||||||
|
[TODO: Link to an issue template for this]
|
||||||
|
|
||||||
|
* Email `announce@dartlang.org, flutter-announce@googlegroups.com`,:
|
||||||
|
|
||||||
|
* Subject: 'Breaking change [bug ID]: [short summary]'
|
||||||
|
|
||||||
|
* Very short summary of the intended change
|
||||||
|
|
||||||
|
* Link to the above mentioned issue
|
||||||
|
|
||||||
|
* A request that developers may leave comments in the linked issue, if this
|
||||||
|
breaking change poses a severe problem.
|
||||||
|
|
||||||
|
### Step 2: Approval
|
||||||
|
|
||||||
|
If there is a general agreement that the benefit of the change outweighs the
|
||||||
|
cost of the change, a set of Dart SDK approvers will approve the change.
|
||||||
|
Adequate time must be allowed after step 1, at a minimum 24 hours during the
|
||||||
|
work week for smaller impact changes, and proportionally longer for higher
|
||||||
|
impact changes.
|
||||||
|
### Step 3: Execution
|
||||||
|
|
||||||
|
If approved, the change may be made.
|
||||||
|
|
||||||
|
After the breaking change had been made, the person who made the change must:
|
||||||
|
|
||||||
|
* Resolve the breaking change issue and make a note that the change has landed
|
||||||
|
|
||||||
|
* Make a note in the [Dart SDK changelog](`changelog.md`) detailing the change.
|
||||||
|
This must be prefixed `** Breaking change:`.
|
||||||
|
|
||||||
|
* Reply to the original announcement email, and make a note that the change is
|
||||||
|
being implemented.
|
||||||
|
|
||||||
|
If not approved, or if the requestor decides to not pursue the change, the
|
||||||
|
requestor must:
|
||||||
|
|
||||||
|
* Reply to the original announcement email, and make a note that the change is
|
||||||
|
has been rejected, with a quick summary of the rationale for that.
|
||||||
|
## Unexpected breaking changes & roll-back requests
|
||||||
|
|
||||||
|
If a developer notices a breaking change has been made in the dev or stable
|
||||||
|
channels, and this change impacts a program that abides to the above defined
|
||||||
|
scope of compatibility, and for which either:
|
||||||
|
|
||||||
|
* No breaking change was announced, or
|
||||||
|
|
||||||
|
* The impact of the change was significantly larger than described in the
|
||||||
|
breaking change announcement
|
||||||
|
|
||||||
|
, then they may file a 'request for roll-back' using the following steps:
|
||||||
|
|
||||||
|
* Create an issue in the Dart SDK issue tracker labelled
|
||||||
|
`roll-back-request` containing the following:
|
||||||
|
|
||||||
|
* If applicable, a link to the associated breaking change request issue
|
||||||
|
|
||||||
|
* A clear description of the actual impact, and if applicable a description of
|
||||||
|
how this differs from the expected impact.
|
||||||
|
|
||||||
|
* A link to the program that was affected, or another program that illustrated
|
||||||
|
the same effect.
|
||||||
|
|
||||||
|
[TODO: Link to an issue template for this]
|
||||||
|
|
||||||
|
Upon receiving such an issue the Dart SDK team will either:
|
||||||
|
|
||||||
|
* Roll-back the change, or
|
||||||
|
|
||||||
|
* Make a quick corrective action to correct the change, or
|
||||||
|
|
||||||
|
* Detail how the change in their opinion does not warrant a roll-back.
|
||||||
|
|
||||||
|
If a breaking change is rolled-back, in addition:
|
||||||
|
|
||||||
|
* The breaking change request issue should be reopened
|
||||||
|
|
||||||
|
### Roll-backs following unexpected changes
|
||||||
|
|
||||||
|
If a roll-back occurs after what should have been a breaking change, the
|
||||||
|
originator of the change is expected to follow the breaking change process to
|
||||||
|
move forward.
|
||||||
|
|
||||||
|
If a roll-back occurs after a breaking change, but where the impact was larger
|
||||||
|
than anticipated, then the impacted party is expected to make a best effort to
|
||||||
|
quickly rectify their program to either not be affected by the breaking change,
|
||||||
|
or in some other way offer the originator a clear timeline for when the breaking
|
||||||
|
change can be landed.
|
||||||
|
|
Loading…
Reference in a new issue