Clarify warning about mime stability

[nox]

NOTE: this crate will remain in 2.0.0-alpha.x until mime stabilizes. Backwards-compatible changes will be backported to the 1.x-maint branch but upgrades to mime will constitute an alpha version bump.

Do you mean that you will wait for mime 1.0 before publishing mime_guess 2? Is there even an ETA for mime 1.0?

Cc @seanmonstar

[abonander]

Yes, I mistakenly released mine_guess 1.0 before my single public dependency, mime, reached 1.0 itself, and by the time I realized the gravity of my mistake, I was already several minor versions in.

This means, to follow semver, I have to release a new major version every time mime is upgraded with a breaking change, which is feasible I guess, but every time people look at mime_guess, they're going to say, "how does such a simple crate have so many major versions? Why is it so apparently unstable?"

Or, instead, I can just remain in 2.0-alpha and just release a new alpha when necessary, then go to 2.0 when mime stabilizes at 1.0. Simple things like new mappings can be backported as well.

[abonander]

Forgot to add, we are discussing mime's stabilization here: hyperium/mime#52

If you have anything to add, please feel free.

[Diggsey]

@abonander unfortunately this is not a good solution: the way cargo works, it will happily allow multiple versions of pre-1.0 crates to exist in a project (ie. both 0.1 and 0.2 versions of a crate can co-exist). However, it will not allow multiple of the same major version, so 2.0-alpha1 cannot co-exist with 2.0-alpha2. This means that mismatched mime versions is not too problematic (you just end up with multiple versions) but mismatched corresponding mime_guess versions are a serious issue.

I don't know a good way to solve this beyond switching the crate name, at least until mime is stabilised.

[abonander]

@Diggsey what about just bumping to 2.0? At this point I don't really care about inflating the major version as long as it makes versioning work correctly again. I can just keep bumping the major version alongside mime upgrades until it finally stabilizes and everything should work correctly, right?

It would help prevent mistakes like this if Cargo warned about releasing a 1.0 while dependencies are < 1.0. It doesn't have to forbid since those dependencies are likely private, but just having the note would have prevented this mistake.

[Diggsey]

Personally, I think it is a bug in cargo that it does not allow multiple pre-release versions to co-exist, and I'm opening an issue for it. I don't really mind what you do here as long as you don't publish another incompatible version until you actually need to 😛

[abonander]

@Diggsey but would releasing 2.0 also remedy the situation? I don't have any backwards-incompatible changes in mind besides mime upgrades.

[Diggsey]

2.0 would be yet another conflicting version, as it could not be linked with any of the 2.0-alpha.x versions. Publishing 3.0, 4.0, etc. each time you need to bump mime would work, but it's a bit of a nasty solution.

[abonander]

Fortunately I don't think mime has too many more pre-1.0 releases to go through though there's still some pending changes to the API. So releasing 2.0 would temporarily not fix the problem, but future releases would be compatible with each other? Seems like a better solution than renaming the crate.

Again, at this point I don't care as much about artificially inflating the major version. In fact if I had just gone ahead and released 2.0 to begin with this wouldn't be an issue either.

I think Cargo not considering pre-release versions compatible is intentional as they could contain breaking changes.

[Diggsey]

Cargo is correct to consider pre-release versions not compatible. The problem is that it does not allow them to co-exist.

For comparison, cargo considers versions 1.0 and 2.0 of a crate to be incompatible (of course) but it does allow them to co-exist: you can transitively depend on both versions of the crate just fine.

In the opposite case, cargo considers versions 1.0 and 1.1 of a crate to be compatible, but it does not allow them to co-exist: you can only transitively depend on one of them. It will force all 1.x constraints to be fulfilled by a single version.

[nox]

No, Cargo lets you have mime 0.2 and mime 0.3, there is no issue with that.

[Diggsey]

@nox ... I never said anything that disagreed with that?

[nox]

Then I don't understand why you said this:

Cargo is correct to consider pre-release versions not compatible. The problem is that it does not allow them to co-exist.

For comparison, cargo considers versions 1.0 and 2.0 of a crate to be incompatible (of course) but it does allow them to co-exist: you can transitively depend on both versions of the crate just fine.

Whenever mime has a breaking bump, the breaking bump has to be propagated in mime_guess as a breaking bump, so releasing a new major version of mime_guess whenever there is a new breaking bump in mime (either from 0.n to 0.n+1 or 0.n to 1.0 or n.0 to n+1.0) is how things are supposed to be done in the crate world.

[abonander]

@Diggsey @nox I think we're confusing pre-1.0 (0.x.y) and pre-release (x.y-alpha|beta.z)

[abonander]

@nox I think @Diggsey is saying that mime_guess 2.0-alpha.5 and 2.0-alpha.6 cannot coexist in the same dependency tree, right?

[Diggsey]

Yes, I'm talking about pre-release versions. Semver says that pre-release versions should be considered unstable, therefore cargo should treat them as though they were separate major versions, and this should work as a solution to the problem here, unfortunately it does not.

[nox]

My bad, I misparsed pre-release as pre-1.0, I'll just go back to my corner.

[abonander]

@Diggsey what is the error that Cargo is reporting anyway? Is it completely forbidding having two different pre-release versions in transitive dependencies?

[Diggsey]

I fixed it now and it'll be annoying to reproduce, but it was just saying something along the lines of "conflicting version requirements on mime_guess crate" with the two pre-release versions specified. The two versions were transitive dependencies of some other crates I depend on.

[nox]

@abonander Ping on this, what's blocking an actual release? Why are we still 2.0.0-alpha.6?

[abonander]

I'm not happy with the mime crate not yet being 1.0, however, I guess I can release 2.0.0 that supports mime 0.3 and when a bump is necessary I'll just release another major version.

[seanmonstar]

I've been working on the mime crate recently, if you want to take a glance at master (the docs may be easier to look at), perhaps that should become 1.0?

[abonander]

Looks fine to me but I only need a tiny subset of the API so I'm not hugely important as far as stakeholders go. It's probably worth discussing on hyperium/mime#52 though.

[abonander]

@seanmonstar any remaining* blockers to releasing 1.0 or you just waiting for more feedback on the API?

[seanmonstar]

@abonander I think I convinced myself to adjust the API yet again, and simply stick to the mimesniff algorithm...

[abonander]

@seanmonstar @nox so if that's going to be a while should I just cut a release against mime 0.3? Servo is the major stakeholder for this crate so I'll defer to what you guys want.

[abonander]

@nox @seanmonstar so if mime 1.0 is going to be a while yet, I'm thinking I should release 2.0 linked to mime 0.3, and then when mime 1.0 releases I will release 3.0.

In #43 I was discussing a new API with @lnicola. I'm thinking this should wait until mime_guess 3.0 so the upgrade to 2.0 has minimum breakage. However, considering the small API surface of this crate I'm wondering if that's necessary and if I can just introduce those changes in 2.0.

I will, of course, be sure to note which version ranges of mime_guess go to which versions of mime in the README.

[abonander]

If seanmonstar/unicase#30 and rust-phf/rust-phf#152 are merged today I will release mime_guess 2.0.0 linked against mime 0.3 followed by mime_guess 2.1.0 which deprecates the existing free functions and adds the new API discussed in #43. The deprecated functions will then be removed in mime_guess 3.0.0 which will link the next mime release, be it 0.4 or 1.0.

I will also make reverse mappings an optional feature (on by default) to give users some control over how much code and static data are generated.

I have also added a table to the README which relates mime_guess versions to mime versions.

[abonander]

Movement on rust-phf has been kinda slow so I might temporarily switch back to the old binary search so I can kick out a release. Opinions?

[lnicola]

I think it would be fine. API improvements are still improvements, and performance is unlikely to be an issue. Some of the users of the crate already cache the results in a hash map, for whatever reason.

[abonander]

I've instead been added as a maintainer for rust-phf and I've been working on a doozy of a 0.8 release.

[abonander]

I have opened a PR for 2.0 which turns off rust-phf temporarily and falls back to a binary search: #48

[abonander]

I'm thinking of requiring new contributions to provide citations as line comments next to the changed mappings, to provide a cleaner audit trail than searching through Git history. This might bloat the source size by a couple kilobytes but it shouldn't affect compile time significantly and wouldn't affect compiled size at all. Existing mappings can have their citations added over time but this will be a lot of busy work. Does anyone have any strong opinions on this?

[abonander]

mime_guess 2.0.0 has been released.