Versioning for diesel

[weiznich]

With the upcoming diesel 2.0 release we want to clarify a few details on our versioning scheme and how certain features interact with our semver guarantees. This post tries to summarize my own ideas and seeks to collect some feedback on them. The result should be a more complete guideline on what is possible and what not.

cc @diesel-rs/contributors @diesel-rs/reviewers @diesel-rs/core

Public API

In the past we defined our public API as everything that is explicitly documented. This excludes quite a lot of types that are exposed via a pub modifier, but are #[doc(hidden)] in practice. I believe that's a good strategy, but we should document that somewhere?
Additionally I think before releasing diesel 2.0 we should go through all those #[doc(hidden)] and decide:

• If we can make them private
• If they are required for some macro, but are not relevant for usage for users. Maybe they should be exposed via some dont_use_this_stuff module that is #[doc(hidden)]?
• If they are required to implement third party backends or used otherwise in a meaningful way. If that's the case we should think about how to expose a corresponding public API.

Minimal supported rust version

We should publicly define a minimal supported rust version and also define what we understand under minimal supported rust version. I tend to define that by myself as that rust version that can be used to compile diesel and some version of it's dependencies. Notability that does not include the promise that users can compile diesel and the latest version of all dependencies using the minimal supported rust version, but only that there exists some set of dependency versions that is compatible with that rust version. We do currently test this via the -Z minimal-version flag from cargo.

The minimal supported rust version and our definition should be documented somewhere.

Feature flags

There are currently the following available features on the main diesel crate:

• default = ["with-deprecated", "32-column-tables"]
• extras = ["chrono", "serde_json", "uuid", "network-address", "numeric", "r2d2"]
• unstable = ["diesel_derives/nightly"]
• large-tables = ["32-column-tables"]
• huge-tables = ["64-column-tables"]
• 32-column-tables = []
• 64-column-tables = ["32-column-tables"]
• 128-column-tables = ["64-column-tables"]
• postgres = ["pq-sys", "bitflags", "diesel_derives/postgres"]
• sqlite = ["libsqlite3-sys", "diesel_derives/sqlite"]
• mysql = ["mysqlclient-sys", "url", "percent-encoding", "diesel_derives/mysql", "bitflags"]
• without-deprecated = []
• with-deprecated = []
• network-address = ["ipnetwork", "libc"]
• numeric = ["num-bigint", "bigdecimal", "num-traits", "num-integer"]

We should document that we cover most features under our semver guarantee, also we should document that enabling the following features explicitly opts out the semver guarantee:

• unstable, is it requires a nightly compiler and may break at any time
• without-deprecated as it removes deprecated parts of our public API
• Disabling the with-deprecated feature for the same reasoning as given above.

For us it should be clear that adding new features (also as default is fine), but removing them is a breaking change.

Also this should be documented somewhere.

Additionally we should think about introducing a i-implement-a-third-party-backend feature, which exposes things we are not willing to include in our normal public API. This feature should probably come with a policy that says: If you use this feature you should threat every minor version increment as potential breaking change. Additionally this would us allow to provide at least some documentation for implementing third party Connection's and Backend's behind that feature flag. cc @fernandobatels here, as they have written such a third party backend using a forked version of diesel due to not having access to certain things. (As I'm one of the maintainers of diesel-oci, there is no ping for the diesel-oci side here)

The documentation for all this stuff should probably be on our web page and the changelog should contain a link there.

[fernandobatels]

The i-implement-a-third-party-backend is good idea.

For example, in my case I need access the SelectStatement fields and the possibility to write a custom select syntax.

PS: I will open a PR with my changes in the future. My implementation of the diesel backend is still in testing.

[pksunkara]

Why is there both with-deprecated and without-deprecated? Cargo features are additive.

[weiznich]

See #1638 for the reasoning. The implementation is additive as it overwrites the with-deprecated feature.