API Stability

[notgull]

In other repos, it has been discussed to include traits like Connection in the public API so that users can supply their own connection types for various operations. See rust-windowing/raw-window-handle#120 for an example of the rationale for this.

How would we feel about a 1.0.0 release that solidified the API, which would make cases like this possible? Not now, I'd say the API still needs some falling to do; (I've felt the burn of a premature 1.0 version thanks to breadx). But, in the distant future, it would be nice to have a stable API.

First off, would this even be possible? I know that there were some breaking changes in the past due to xcb-proto making Rust-semver-incompatible version bumps. Maybe it would be possible to avoid this somehow?

Second, what kind of changes would we need to ossify the API? The traits, for the most part, are stable, but what else needs to be bolted down?

[psychon]

Second, what kind of changes would we need to ossify the API?

Early on, I started opening issues for everything that came to my mind. At some point, I started using labels to organise this. I feel like I haven't used labels recently....

Anyway, there is a stable API label that is supposed to be used for everything that might be an API break: https://github.com/psychon/x11rb/issues?q=is%3Aopen+is%3Aissue+label%3A%22stable+API%22
Two of the three API breaks for the upcoming release (which I hopefully will release today) comes from one of these issues: #156 and #178

So, this label has the ideas that are necessary for this. Some of these are quite vague (looking at you, #73). Others are quite concrete, like #178. However, #178 was marked was stable API until a moment ago, so this list is also not complete...

The traits, for the most part, are stable, but what else needs to be bolted down?

Random idea that I do not actually like: Split up into even more crates. "Core with stable API" (e.g. request sending trait) and "generated code and everything depending on generated code". Then only parts would need to be stable and other parts can continue to break. That would also solve the "xcb-proto causes API changes"-issue. But did we actually ever actually have that? I don't remember. 🤔

Besides that... dunno.