Skip to content

Commit

Permalink
Document process for breaking changes
Browse files Browse the repository at this point in the history
  • Loading branch information
workingjubilee committed Aug 20, 2024
1 parent aadb894 commit 2d2ef06
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 0 deletions.
6 changes: 6 additions & 0 deletions src/breaking-changes/new-trait-impls.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,12 @@ let b = Arc::from("a");
will no longer compile, because we've previously been relying on inference to figure out the `T` in `Box<T>`.

This kind of breakage can be ok, but a [crater](https://github.com/rust-lang/crater/blob/master/docs/bot-usage.md) run should estimate the scope.
When implementing traits known to have this problem, crater should be run before initiating FCP,
so information on the scope of the breakage is available before deciding to accept the change.
This can include, but is not limited to,

- From
- FromIterator

## Deref coercion breaks when a new impl is introduced

Expand Down
6 changes: 6 additions & 0 deletions src/breaking-changes/summary.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,11 @@ Breaking changes should be avoided when possible.
[RFC 1105](https://rust-lang.github.io/rfcs/1105-api-evolution.html) lays the foundations for what constitutes a breaking change.
Breakage may be deemed acceptable or not based on its actual impact,
which can be approximated with a [crater](https://github.com/rust-lang/crater/blob/master/docs/bot-usage.md) run.
Running crater should be done if nontrivial breakage is expected, so the information is
available during the final comment period.

If the impact isn't too high, looping in maintainers of broken crates and submitting PRs to fix them can be a valid strategy.

# Breaking and the trains
If a PR is merged and it turns out to have caused code to not compile during the nightly release cycle,
unless there is a trivial fix, the PR should be reverted and a crater run should assess the impact.

0 comments on commit 2d2ef06

Please sign in to comment.