How to handle breaking releases, and how can we help users?

[azerupi]

Current master has breaking changes to the configuration file. I expect there will be more breaking changes in the future as we improve and refactor mdBook. So we can't guarantee stability. However, users might automate deployment of books through CI and we don't want to break their deployments every time we make a breaking release!

So, can we figure out a way to pin CIs to a specific non-breaking version range of mdBook (like cargo does) so that the user can choose when to update to the breaking release?

Ideally we would need to come up with a solution that all the users can easily implement in Travis (or other CIs). Post it on the different forums and projects known to use mdBook and give some time to the users to migrate. Then we can release the 0.1.0 breaking release.

This issue is particularly relevant for the different books in the Rust community (TRPL2, Cookbook, ...), I'm not sure how they handle deployments currently?

@steveklabnik @budziq @frewsxcv

Feel free to tag anyone who might have an interest in this discussion.

[budziq]

cargo install supports --vers flag also for binaries
Basically we can endorse all users to pin their CI to specific mdbook binary version like below:
cargo install mdbook --vers 0.0.22

Then changing version of mdbook with which the artifacts are built in CI would have to be conscious decision on user side. And if they would like to benefit from bugfixes and new features they would have to follow some porting guideline (possibly a trivial 1-4 liner in docs).

cc @brson

[azerupi]

Beginning with the 0.1.0 which should be the next release, we will bump the minor version every time we make a breaking release. I just tested and cargo supports cargo install mdbook --vers "0.0.*" so I think we should start by making users use that instead of just any version.

[budziq]

cargo install mdbook --vers "0.0.*" (or any other incomplete semver triple) produces a depreciation warning from cargo

warning: the `--vers` provided, `0.0.*`, is not a valid semver version

historically Cargo treated this as a semver version requirement accidentally
and will continue to do so, but this behavior will be removed eventually

since rust-lang/cargo#3321 cargo depreciated using --vers with "semver requirements" (as in lib requirement) in favour of specific "semver versions".

Imho it is a shame as it was a nice feature.

[steveklabnik]

Basically we can endorse all users to pin their CI to specific mdbook binary version like below:
cargo install mdbook --vers 0.0.22

Yes, this is what I'd suggest as well.

[azerupi]

since rust-lang/cargo#3321 cargo depreciated using --vers with "semver requirements" (as in lib requirement) in favour of specific "semver versions".

Oh so you can't specify semver ranges for binary install? That's a bummer...

[azerupi]

Ok, we should start pinging projects that use mdBook to warn them of an 'imminent' breaking release and that if they deploy with CI they should pin the version number. If you know of any projects using mdBook, please let me know here!

• Rust Cookbook is already using a pinned version.
• The Rust Programming Language is using master.
• Bindgen is using an unpinned version. Specify version of mdbook in the deployment script rust-bindgen#779
• IntermezzOS is using an unpinned version. Is okay that way.
• Discovery is using pinned but outdated version
• Redox not sure if they automatically deploy? redox-os/book#100
• Lumol is using an unpinned version. Pin version of mdBook lumol-org/lumol#193
• Clap not sure if they automatically deploy? Pin version of mdBook clap-rs/clap-book#4
• gentle-intro - not sure if they deploy automatically
• wayland-rs - uses unpinned version Pin version of mdBook Smithay/wayland-rs#121
• rust-anthology - uses unpinned version Pin version of mdBook brson/rust-anthology#12
• ... ?

[steveklabnik]

TRPL is using a pinned version, not master: https://github.com/rust-lang/rust/blob/master/src/tools/rustbook/Cargo.toml#L11

I am happy with intermezzOS automatically updating, no need to warn me 😄

[budziq]

Hi these are the ones I know of:

• gentle-intro - not sure if they deploy automatically
• wayland-rs - uses unpinned version
• these two are owned by Steve so I post them just for refference ;)
  • nomicon - uses unpinned version
  • reference - uses unpinned version

[azerupi]

TRPL is using a pinned version, not master

Good to hear, I suppose that applies to all the books in the Rust org? :)

[steveklabnik]

Yes, the same thing is used for all of the ones on doc.rust-lang.org.

…

On Wed, Jun 21, 2017 at 2:54 PM, Mathieu David ***@***.***> wrote: TRPL is using a pinned version, not master Good to hear, I suppose that applies to all the books in the Rust org? :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <https://github.com/azerupi/mdBook/issues/327#issuecomment-310172554>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABsilDBN734CtZ7WsUmdTJXQ0tWc6fvks5sGWbrgaJpZM4N4Q8X> .

[azerupi]

I have made a PR to cargo rust-lang/cargo#4229 to add semver ranges to cargo install --vers. Once this is merged we can start to recommend users to pin the version of mdBook like this

cargo install mdbook --vers "^0.0.22"

It should already work with Cargo right now (with a deprecated warning) but if the PR gets merged we are guaranteed that this behaviour will stay and that the deprecated warning will go away in future releases.

Edit: PR has been merged into Cargo! 🎉

[azerupi]

I have opened an issue in each repository listed here. Maybe I should also make an announcement on the users forum?

Another thing that needs to be done is to mention the version pinning for CI scripts in the readme. This will hopefully allow new projects to pick up the good habit from the start.

[budziq]

I should also make an announcement on the users forum?

We have a users forum 😸? How can one find it?

Another thing that needs to be done is to mention the version pinning for CI scripts in the readme. This will hopefully allow new projects to pick up the good habit from the start.

Good idea. We have to update the docs anyway for 0.1.0 release
https://github.com/azerupi/mdBook/issues/368

[azerupi]

Well I was talking about the Rust user forum 😄

[budziq]

Well I was talking about the Rust user forum 😄

Also a good idea. https://www.reddit.com/r/rust/ is also a popular place for rustaceans to visit

[elinorbgr]

I have a question regarding this, how does

cargo install mdbook --vers "^0.0.22"

interact with

cargo install-update -a

that I use in my CI ?

[budziq]

@vberger
cargo install-update -a does not seam to be a standard cargo command so I can't really say.

Do you use some helper crate to get this command?

[elinorbgr]

yes: https://github.com/nabijaczleweli/cargo-update

This allows me to use the travis cache to avoid rebuilding mdbook & friends every time (this tends to make the builds timeout, as some dependencies are quite long to compile), while still keeping them up to date.

I was just asking in case you knew, but I should probably ask them directly.

[budziq]

@vberger I've tested the cargo-update crate with your command.
It forces installation of newest mdbook available via crates.io overwriting the pinned version from --vers "^0.0.22".

So basically when mdbook v0.1.0 is suddenly released you would have to call
cargo install mdbook --vers "^0.0.22" --force (to install the older version if newer is installed)
right after cargo install-update -a and prior to mdbook build.

But I understand that travis will have to build mdbook at least once unless the mentioned travis cache is smarter than I think ;).

[azerupi]

how does cargo install mdbook --vers "^0.0.22" interact with cargo install-update -a

cargo install mdbook --vers "^0.0.22" will install the latest version compatible with 0.0.22 in a semver sense. As far as I know, cargo install-update doesn't offer any flag to specify a version so it will always update to the latest version. Maybe they would consider adding this feature? It's worth opening an issue on their repo.