RFC 0013: Experimental features

[Redblueflame]

Rendered view

This PR sets the base for experimental features support for the QSL.

It depends on #12, that sets up the base this RFC is built on.

This PR may need to wait until the QSL working group is formed, but can still be merged if wanted.

[Redblueflame]

This PR is now ready for review. The main potential pain point will be for the versioning, I'm open to all suggestions on the matter, as it doesn't really explicit anything in the current state.

If you have any suggestion or concern, do you hesitate to speak out, I'm sure we will be able to work things out :)

[Redblueflame]

Updated the versioning policy with experimental features, after the discussions with @TheGlitch76.

[TelepathicGrunt]

If I am reading this right, to use any experimental apis in QSL, people need to manually enable it? If so, no offense, but that’s a really really bad idea.

In Fabric API, they use deprecated annotation to mark things as experimental and one of those things was Biome Modification API. I had to practically beg people to use the API because people got scared of the deprecated annotation. And some were terrified of the strikethrough and told me they really don’t feel comfortable using it. It was bad. And I still constantly have to help people and tell them the to use the API as it is the recommended way of adding to biomes in 1.16.2+

Now, gating the experimental api behind a option that the modder had to turn on is a step even further, and in my option, is going to scare people even further than deprecated ever will. They will now struggle to use experimental features as they won’t know how to turn it on and think the QSL is broken as a result. And others will think experimental is super dangerous that it had to be locked away behind an option which means it will be even harder for me to convince people to use Biome Modification API.

The ideal way I would handle this is, no strikethroughs. No forcing an option to be enabled. No roadblocks at all. Even experimental APIs added are going to become the recommended way of doing something as soon as it exists. Just put a large comment on it so when it breaks due to an experimental change, modders can check the method’s comment to see it is experimental, how it works, and what alternatives if there is any but most likely, there isn’t any. Only then will support stop being flooded by people sheepishly asking if there is any alternatives for the “dangerous” Biome Modification API when there is none.

[Redblueflame]

If I am reading this right, to use any experimental apis in QSL, people need to manually enable it? If so, no offense, but that’s a really really bad idea.

You read it right, people need to manually / automatically enable experimental features.

In Fabric API, they use deprecated annotation to mark things as experimental and one of those things was Biome Modification API. I had to practically beg people to use the API because people got scared of the deprecated annotation. And some were terrified of the strikethrough and told me they really don’t feel comfortable using it. It was bad. And I still constantly have to help people and tell them to use the API as it is the recommended way of adding to biomes in 1.16.2+

The main objective of this is to prevent the usage of strikethrough, but still mark it as "it may break anytime, use it at your own risk", and the way to do so would be to explain it better to modders. Deprecated functions, even if used as experimental ones may be really scary to modders, but an opt-in that explains exactly what it does, as the error message present in the RFC that I will copy should explain it better to modders:

C:\Users\User\project\src\main\java\org\quiltmc\test\Testing.java:9: error: The feature ccc is marked as experimental, but not enabled in the build.gradle file.

To enable the experimental features, please add the following lines to your build.gradle file: 
quilt {
  //... 
  experimentalModules "ccc", "aaa"
}

An alternate way to explain it would be the following:

C:\Users\User\project\src\main\java\org\quiltmc\test\Testing.java:9: error: The feature ccc is marked as experimental, but not enabled in the build.gradle file.

Experimental features are functionalities that, while technically ready, miss enough testing to be stabilized. They are safe to use, but the API surface may break with a migration helper. Learn more about them at (LINK TO DOC)

To enable the experimental features, please add the following lines to your build.gradle file: 
quilt {
  //... 
  experimentalModules "ccc", "aaa"
}

The objective of this is to educate modders about how this system works directly in their IDE/build tools and directly embarks developers on how to use the features.

Just remember that this is put in place so that API changes don't magically break mods that do not know that they are using experimental features that may change at any time, breaking the backward compatibility, and forcing a major version change for every little change in a newly created feature.

The ideal way I would handle this is, no strikethroughs. No forcing an option to be enabled. No roadblocks at all. Even experimental APIs added are going to become the recommended way of doing something as soon as it exists. Just put a large comment on it so when it breaks due to an experimental change, modders can check the method’s comment to see it is experimental, how it works, and what alternatives if there is any but most likely, there isn’t any. Only then will support stop being flooded by people sheepishly asking if there is any alternatives for the “dangerous” Biome Modification API when there is none.

The main issue I have with this is that there are simply far too many ways to miss the experimental module use, and simply break semver every time without modders even knowing it. I do understand that having the warnings too visible may be an issue, but having it hidden too far is also a big one.

The fact that adding an experimental feature is use and forget as long as there is no change is a somewhat OK compromise for both QSL devs and modders, as it allows to apply the Move fast, break things on experimental features, while still having the Stay backwards-compatible for stabilized features that are not really likely to change until the big version change, where QSL may do a major bump, and where deprecated functions of the cycle may be removed and replaced with the now stabilized features.

All in all, for this to be perfect, we may need another feature, that will be explained in another RFC, Migration Helpers, small files that explains how to migrate your project to the new features in detail (like a helping hand).

[Redblueflame]

Digging this RFC from the dead to evaluate the interest in this feature. With the start of work on the build tools for quilt, and having more time to perfect the annotation processor service, to finish the proof of concept.

I've also started work on a RFC for migration helpers, in order to facilitate use of experimental APIs.

[Akarys42]

Is this PR still relevant?