Skip to content

Commit

Permalink
Space out readme sections
Browse files Browse the repository at this point in the history
  • Loading branch information
dtolnay committed May 19, 2019
1 parent b89bf02 commit 95eabeb
Showing 1 changed file with 12 additions and 0 deletions.
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ without requiring a coordinated upgrade across its downstream dependency
graph.** The trick is built around having one version of your library declare a
dependency on a newer version of the same library.

<br>

## Illustrative example

The Rust library ecosystem has a history of traumatic library upgrades. The
Expand Down Expand Up @@ -65,6 +67,8 @@ would be broken, and this needs to be reflected in the semver version of the

Here is where things go wrong.

<br>

## Coordinated upgrades

Suppose we make the fix and publish it as a breaking change.
Expand Down Expand Up @@ -99,6 +103,8 @@ months ([servo/servo#8608]).

[servo/servo#8608]: https://github.com/servo/servo/issues/8608

<br>

## The trick

At the heart of the problem is having a widely used API caught up in the
Expand Down Expand Up @@ -143,6 +149,8 @@ The libcpocalypse scenario is averted because users of `libc` can upgrade from
0.2 to 0.3 at their leisure, in any order, without needing to bump their own
semver major version.

<br>

## Advanced trickery

With some care and creativity, the technique above can be generalized to lots of
Expand All @@ -160,6 +168,8 @@ in this repo demonstrates some types of changes that can be accomodated.
[`semver_trick::before::Moved`]: https://docs.rs/semver-trick/0.2.0/semver_trick/before/struct.Moved.html
[`semver_trick::after::Moved`]: https://docs.rs/semver-trick/0.3.0/semver_trick/after/struct.Moved.html

<br>

## Limitations

This is not the silver bullet that solves all occurrences of dependency hell.
Expand All @@ -178,6 +188,8 @@ following concrete examples:

[sealed]: https://rust-lang-nursery.github.io/api-guidelines/future-proofing.html#c-sealed

<br>

## Other tricks

Where the semver trick is not applicable, it can be possible to mitigate the
Expand Down

0 comments on commit 95eabeb

Please sign in to comment.