Policy for unstable dependencies

[KodrAus]

bitflags has taken responsibility for shipping features for libraries it integrates with. Some of these libraries are unstable, so updating them in bitflags would either require a breaking version bump or shipping a new feature for the new version. The goal of this issue is to come up with an agreed upon policy for managing these features that avoids accumulating unstable features indefinitely, but also lets users make use of unstable libraries that they want to integrate with bitflags.

I've got two candidate policies in mind, but would be keen to hear any others:

1. Use a RUSTFLAGS cfg, like bitflags_unstable to opt-in to unstable features. In this policy, we'd ship, for example, a zerocopy feature, but you'd need to pair it with the RUSTFLAGS cfg before we'd actually use the library. When zerocopy released a new breaking version, we'd update to it.
2. Use versioned features, but occasionally shed them in major versions of the library. In this policy, we'd ship, for example, a zerocopy-0-6 feature. When zerocopy released a new breaking version, we'd add a zerocopy-0-7 feature. At some point, we'd release a bitflags 3 that pruned off some of these older features without breaking public APIs. We could do these releases, say, every 6 or 12 months.

[KodrAus]

I'm more inclined for policy 1, it's less of a burden for us to maintain. We wouldn't create a proliferation of bitflags versions, and wouldn't be stuck adding an unbounded number of features for dependencies that are particularly unstable. The drawback of this policy is that end-users can only be applications with enough control over their build process to add that RUSTFLAGS cfg. They'd also need to keep on top of unstable releases at the same cadence as bitflags.

[MarijnS95]

I definitely prefer policy 2: might be a bit more overhead (though for nalgebra it was just reexporting an older implementation when semantics didn't change) but doesn't mess with folks having to manually set RUSTFLAGS all the time to make their crates (or explicit/implicit dependencies thereof!) compile.

[qwandor]

I would prefer policy 2, as the dependency on bitflags and zerocopy is often an indirect dependency, and having to set RUSTFLAGS on a binary just because some dependencies happen to be in you tree is unusual and surprising.

[KodrAus]

The case of nalgebra with glam is actually a good example of what I'd really like to avoid in bitflags. It currently has 10 features to support some number of minor versions of this single dependency. Even when the implementation behind those features is small and broadly similar that's still a lot to carry forwards.

I think there's an expectation that when an unstable library releases a new minor version that users should upgrade to stay current. There's no longevity to those unstable releases because nothing is fixed yet. For example, I doubt someone will come along and ask nalgebra to support glam 0.13. There's also no reason a library couldn't aggressively publish new minor versions every few weeks while iterating.

To keep bitflags healthy in spite of any release cadence of a particular unstable library we'd either need to make regular breaking releases to prune them (policy 2), or handle them externally to our own semver (policy 1). For policy 2, that would probably also mean committing to not making any other breaking changes to bitflags itself going forwards, or those legitimate breaking releases will become difficult to spot amongst the innocuous releases that prune unstable features.

[KodrAus]

For what it's worth, even though my preference is policy 1, I'm not against policy 2, so long as we're comfortable with avoiding making releases that legitimately break things, or in being very selective about the unstable libraries we'll support.

[qwandor]

Can we decide this soon? It's blocking updating a bunch of things in AOSP to bitflags 2, which we'd like to do sooner rather than later.

[KodrAus]

@qwandor Ok, we committed in bitflags 2.x to taking responsibility for integration with other libraries, so we should go ahead and actually do that. Do you think this is a workable policy?

• bitflags will add support for unstable libraries using regular Cargo features, like zerocopy_0_7.
• bitflags will make roughly annual major releases in which it will prune old versions of unstable dependencies as needed. Other breaking changes won't be made in bitflags.
• bitflags will only add unstable dependencies that are "stable enough" that they're unlikely to make more than 3 breaking version bumps between major bitflags releases (annually).

I think that strikes a reasonable balance for people who want to use unstable dependencies in bitflags and lets us keep bitflags moving forwards.

[qwandor]

That sounds like a reasonable policy to me. Thanks!

[KodrAus]

I think we'll end up amending this a bit to avoid needing to add direct support for any unstable libraries at all (and so not need a policy for maintaining them). My approach is outlined here: #348 (comment)

[KodrAus]

We no longer need a policy for unstable dependencies now that #348 is merged, which allows you to integrate with external libraries, without bitflags itself needing to depend on them.

Thanks for all the input everyone!