Future-proofing API (Qt 7 etc.)

[ratijas]

Summary

This thread is intended as a general discussion of thoughts on future-proofing APIs and forward & backward compatibility.

I don't have much to say on topic just yet, except I was surprised to notice they are already taking notes for Qt 7.

Rationale

At the moment of writing, it seems like Qt 5 is going to stick around for a while, because of how widely used it is, and since upgrading code base to Qt 6 might not be as seamless as we'd want it to (some important modules haven't been ported yet). And Qt 6 isn't going to be the latest and greatest forever either, as indicated by those various TODO comments across the code.

Roadmap

Currently, the most hard-coded part of this crate is the documentation. Every link references Qt 5 docs regardless of an actual version specified and found. There was an attempt to replace all the docs boilerplate with a #[qt_doc] proc-macro, and was only abandoned due to personal reasons (such as constant lack of time and being a lazy ass), the implementation was mostly done though.

Second, what about docs.rs? At the moment, it only builds and renders docs for single platform, single fixed feature set. It is possible to specify multiple targets via cargo.toml package metadata, but there is no way to build a create twice with different features — which is what we would want to in order to show Qt 5/6 specific API and links.

Anyway, some libs/modules of Qt 5 are in the docker image used by docs.rs, but even qt5-declarative is missing, and Qt 6 isn't mentioned at all (they would probably conflict anyway).

To summarize: we should do something about docs.rs to have separate builds for different major versions of Qt.

Lastly, we should have some sort of internal documentation for contributors (namely, "CONTRIBUTING.md") to describe there the usual pattern of #[cfg] + #ifdef routine that we already have in code.

More ideas on topic are always welcome!