Reword warning about extension compatibility in README

[Calinou]

GDExtension has limited forwards compatibility available since Godot 4.1, so the warning, while still relevant, can be made less prominent.

• See Use GitHub admonition syntax for the warning in README #1543 (comment)

[dsnopek]

Thanks! This definitely seems like an improvement to me

[Bromeon]

I think the new wording is still a bit strong? Also, it's repeated too many times imo:

compatibility with GDExtension is not as strictly guaranteed as with GDScript or C#.

Current limitations in the GDExtension system may also require compatibility-breaking changes
to be lifted.

In practice, this means that GDExtension compatibility can occasionally break across minor Godot releases.

Some compatibility breakage is to be expected

This sounds a bit dreadful. What I'm worried about is that this discourages binding and extension maintainers from investing into long-term projects.

While it's an easy cop-out for us in the GDExtension team, I'd prefer if we held ourselves accountable on not breaking compatibility unless absolutely necessary, and this is also how we've operated since 4.1, sometimes even reverting the removal of broken methods just for this.

What I would prefer instead is to document that we generally maintain GDExtension compatibility from 4.1 onward, however there may be rare scenarios where breakage is needed, but these need to be well-justified.

---

Furthermore, I believe godot-cpp should be mentioned separately from GDExtension. While both are maintained by overlapping groups of people, GDExtension meanwhile has many more clients, so its design is not only driven by the C++ bindings. Such a separation would also allow a more lenient compatibility policy in godot-cpp while maintaining API stabilitiy on the C interface.

---

TLDR: Backwards compatibility with 4.1 is a core goal and not just a potential, nice side effect. godot-cpp is allowed to follow a separate policy.

[dsnopek]

What I'm worried about is that this discourages binding and extension maintainers from investing into long-term projects.

While it's an easy cop-out for us in the GDExtension team, I'd prefer if we held ourselves accountable on not breaking compatibility unless absolutely necessary, and this is also how we've operated since 4.1, sometimes even reverting the removal of broken methods just for this.

Hm, yeah, our track record has been very good with regard to binary compatibility since 4.1, and, in practice, we put a lot of effort into not breaking compatibility. So, we could publicly make a stronger statement on compatibility.

My main worry with doing something like that, has been a fear that there is some serious issue (like the one that forced breaking compatibility in 4.1) that we haven't found yet, and making strong compatibility promise will hurt developer trust if we are forced to break it. However, I guess with each minor Godot version, and as GDExtension gets more and more use, that becomes less and less likely.

Furthermore, I believe godot-cpp should be mentioned separately from GDExtension. While both are maintained by overlapping groups of people, GDExtension meanwhile has many more clients, so its design is not only driven by the C++ bindings. Such a separation would also allow a more lenient compatibility policy in godot-cpp while maintaining API stabilitiy on the C interface.

This makes sense to me. We're quite strict with regard to binary compatibility for the GDExtension interface and even source compatibility for gdextension_interface.h, but much looser with source compatibility for godot-cpp.

We can discuss this some more at the GDExtension meeting in ~10 minutes :-)

[Bromeon]

Yeah, there's probably a balance to strike. On one hand, it's nice if people can see that a project takes stability seriously (especially considering all the effort we put in to ensure just that), on the other hand we don't want to design ourselves into a corner.

So I wouldn't state the compatibility as a guarantee, but as some best-effort goal we strive towards.

---

Incidentally, I think we haven't discussed a strategy on breaking changes, simply because the policy so far was "we don't do it". But maybe it's good to have some ideas in place just in case (e.g. deprecation periods, epochs/editions, ...). This will become more relevant as we have more minor versions.

[dsnopek]

Discussed at the GDExtension meeting and we discussed a number of ideas:

• To soften the message we could say that we "reserve the right to break compatibility" to fix issues, but that we haven't had to do so since 4.1, and we strive not to break compatibility
• We should say something about how building a GDExtension for 4.1 should work in Godot 4.2, 4.3, etc, but a GDExtension built for 4.2 won't work in Godot 4.1
• This explanation may be getting kind of long, and perhaps we should write something short in the README that links to a longer explanation in the docs?

[HuntJSparra]

Some thoughts in addition to what was discussed at the GDExtension meeting:

• I agree that the current wording could scare off developers. Something along the lines of "GDExtension strives for compatibility with future versions. Breaking compatibility is a rare, last resort for serious issues that cannot be solved otherwise." would show GDExtension's stability while still allowing for breakage.
• Regarding shortening the explanation, I think only one of the three paragraphs is needed to discuss compatibility specifically. Each paragraph has valuable information, but there is also a lot of overlap between them (all state compatibility breakage may occur). Of the three, the second paragraph is my personal favorite because it is short and actionable. Also, its "occasional" breakage sounds less serious than the "not as strictly guaranteed" compatibility and "expected" breakage in the first and third paragraphs.
• When describing how GDExtension is not backwards compatible (e.g., a 4.2 extension does not work for 4.1), is there some quick guidance we can provide such as "To maximize compatibility across Godot versions, use the lowest version of GDExtension that has the features you need. Bug fixes are backported to older versions."? Personally, my instinct with packages is to use the newest (stable) version, but that's troublesome for extension maintainers who want to support older Godot versions.