Cargo: Release Cargo 1.0

[bstrie]

Our initiative towards stability for the Rust ecosystem this year ought to encompass tooling as well, especially crucial tools that are shipped with the compiler. I only just realized that Cargo was pre-1.0 by reading an article listing the precise versions of each tool it uses ( https://medium.com/@ianjsikes/get-started-with-rust-webassembly-and-webpack-58d28e219635 ); seeing "version 0.19.0" gives a mistaken impression as to the stability of Cargo which AFAIK shouldn't have breaking changes at all by now (at least not to the CLI), and given Cargo's close association to rustc it reflects poorly on Rust's stability as well. Is this simply a matter of bumping the version number to 1.0? If not, then edit this text to turn this into a tracking issue for Cargo 1.0.

[bstrie]

The question of how Cargo's version number ought to track rustc's has been raised. To make it easier on users, IRC has proposed syncing Cargo's version number with rustc's, so instead of a 1.0 release it would actually be a 1.19 release (er, optimistically speaking, that is). This raises two further minor questions:

1. What would happen if we did want to make a breaking change to one and only one of these libraries? Should we bump both versions? What about patch releases?

2. Should we have this same policy for all other projects that eventually want to be shipped with rustc, e.g. rustup and RLS?

[alexcrichton]

In my mind it's impossible for Cargo to have any sort of breaking change at this point in the normal sense, it's got the exact same stability story and guarantees as rustc itself. Along those lines this would be a purely cosmetic change, just changing a few version numbers here, I think we have no leeway to proposing any change to Cargo that we wouldn't already be comfortable proposing.

Cargo-as-a-library will never be stable and will continue to publish a new major and breaking version each release of Cargo, we're not at all ready to provide any guarantees there.

I would personally lean towards just making cargo's and rustc's version the same, less numbers to think about. That means, however, Cargo-the-CLI-tool and Cargo-the-library would have different versions.

[bstrie]

@alexcrichton today Carol was telling me that she might still have some potential breaking changes in mind for some of the CLI options, or at the very least would want to do an audit of the CLI before we stabilize it. Don't really know what that specifically entails or how extensive the changes she has in mind are.

I think it's reasonable to have Cargo-the-tool have a stable version number while itself depending on an unstable "libcargo" or somesuch.

[steveklabnik]

One such breaking change is to change cargo new to be cargo new --bin
instead of cargo new --lib.

On Fri, Jun 23, 2017 at 3:57 PM, Ben Striegel [e-mail]
wrote:

@alexcrichton https://github.com/alexcrichton today Carol was telling
me that she might still have some potential breaking changes in mind for
some of the CLI options, or at the very least would want to do an audit of
the CLI before we stabilize it. Don't really know what that specifically
entails or how extensive the changes she has in mind are.

I think it's reasonable to have Cargo-the-tool have a stable version
number while itself depending on an unstable "libcargo" or somesuch.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/rust-lang/cargo/issues/4211#issuecomment-310758930,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABsioa07ndwZ7E1YV7rKKusQ8TiaqcHks5sHBimgaJpZM4ODAKQ
.

[alexcrichton]

I do realize that "moving to 1.0" sounds like a tempting time to make a bunch of changes, but the fact of the matter is that Cargo's stable right now. Any intention to change behavior I believe would require a transition plan regardless of Cargo's version number.

We could do a scrutiny leading up to 1.0, but not being 1.0 doesn't buy us any extra leeway in my opinion.

@steveklabnik I'd actually imagine that could change at any time!

[carols10cents]

I do realize that "moving to 1.0" sounds like a tempting time to make a bunch of changes, but the fact of the matter is that Cargo's stable right now. Any intention to change behavior I believe would require a transition plan regardless of Cargo's version number.

We could do a scrutiny leading up to 1.0, but not being 1.0 doesn't buy us any extra leeway in my opinion.

So for example, deprecating --host on publish (because it actually wants an index) and then repurposing --host to actually be a host: we just deprecated host, and i figure that should go through a Rust release cycle, and then we can repurpose-- but wouldn't repurposing then require a semver 2.0 if cargo was at semver 1.0? Or would we get away with it because we're fixing a bug? Similarly with the change steve mentioned!

Cargo-as-a-library will never be stable and will continue to publish a new major and breaking version each release of Cargo

I continue to maintain that the way you say "major version" meaning the x in 0.x when the leading version is 0 is confusing because that's not how the spec defines "major version" :P

[matklad]

:+1: for making Cargo binary to use the same version as rustc itself, but keeping Cargo library at 0.x :)

Regarding the stability of Cargo CLI, I wouldn't say that the whole CLI is a public API (it's public, but it isn't necessary an API), so changing CLI without major version bump seems acceptable to me (provided that we are sure that it causes minimal amount of hassle in practice).

To me, stability means that old code continues to work as it always used to. So as long as Cargo.toml, Cargo.lock, and crates.io registry are "stable" and any package can be used as a dependency, even if it was published long ago, I would say that Cargo has stability.

In contrast, I don't see changing cargo new default from lib to bin as breaking stability, because this can't affect old crates, and so I wouldn't say that this default is in fact a part of an SemVer protected API :)

That said, Cargo is effectively stable, so imo we should mark it as 1.smth and then consider removing old stuff, because we are de facto 1.smth :)

[matklad]

That means, however, Cargo-the-CLI-tool and Cargo-the-library would have different versions.

What about renaming Cargo-the-library to something like cargo_internals? I feel some people assume that using cargo crate from crates.io is a supported way for extending cargo. Renaming it as cargo_internals will signal that it is probably not a stable public API :)

[alexcrichton]

@carols10cents oh I'd imagine we could change a flag like --host any time we want, I don't think it's actually possible to effectively even use it outside of Cargo's tests!

@matklad I think you and I are basically in agreement on the CLI aspect. I push back a little on the cargo_internals change, but not much.

[vmchale]

@steveklabnik if you want that functionality, you can always use a shell alias, or a dedicated too that makes templated projects.

[ashleygwilliams]

after chatting with @carols10cents about this, and given the current epoch RFC, perhaps this issue needs an RFC, or, at least perhaps, a meeting to chat about direction and how to move this forward. thoughts? 💁

(carol is putting this on the cargo team proactive list ✨ )

[matklad]

We've discussed this at today's meeting, and decided that we change the version of the binary so that cargo --version says1.26.0 (i.e, to match the version of rust exactly). The binary is de-facto stable, we absolutely can not break it. The new --version basically just reflects reality.

At the same time, we make no commitment to the stability of Cargo the library, and we continue to use the weird 0.x + 1.y version scheme for it :-)