fabric
fabric copied to clipboard
FabricMC
[RFC] Experimental APIs
In order to support API features that are likely to change (1.16 nether biome selection) or difficult to get right from the start, I am proposing to offer experimental APIs in Fabric API. Those APIs are marked via @Deprecated and can both extend existing modules or form new ones.
The @Deprecated annotation use is in line with how Java annotates its preview features, which serve a similar purpose. Additionally the associated Javadoc has to include @deprecated Experimental feature, may be removed or changed without further notice <optional explanation why it is experimental>.
Addition of and incompatible changes to experimental features will incur a minor version bump, the major version and module version (v0/v1/...) remain the same.
We may add another annotation targetting classes, fields, and methods to accompany @Deprecated (for easy lookup, added to api base most likely, or use guava @Beta as well)
Quick vote:
:+1: for guava @Beta annotation etc. in addition to @Deprecated on snapshot hooks
:-1: for just @Deprecated on snapshot hooks
Quick reasoning:
@Beta alone cannot warn users efficiently. @Deprecated alone cannot distinguish from apis scheduled for release-stage removal or in no-source distributions. Combined would be the most informative.
Another quick note: We talked about jetbrain annotations has annotations like @ApiStatus.Experimental, which may serve notification purposes with ide integration.
Jetbrains Annotations are useful for stuff like ScheduledForRemoval and Experimental, but do IDEs support them?
Here are all of the annotation APIs I know of:
- JetBrains Annotations - Maven
- Supported by JetBrains IDEs by default
- Includes several annotations for APIs (
Experimental,Internal,ScheduledForRemoval,AvailableSince,NonExtendable, andOverrideOnly) - Includes several other annotations related to compile-time checks, safety, and method contracts
- @API Guardian - Maven
- Supported by JetBrains IDEs by default
- Includes one annotation with an enum for levels of support (
INTERNAL,DEPRECATED,EXPERIMENTAL,MAINTAINED, andSTABLE)
- Guava Annotations - Maven
- Supported by JetBrains IDEs by default
- Includes one annotation for APIs (
Beta) - Includes three other annotations related to GWT and testing
I can't speak on Eclipse support as I haven't used it in like six years.
I personally prefer JetBrains Annotations because they allow showing detailed API info and additional optional info.
Here are the cons of each:
- JetBrains Annotations
- Maybe not interpreted by other IDEs? An annotation processor is preferable.
- API Guardian
- Too few associated tools available from official site (e.g. no annotation processor)
- Guava Annotations
- No standalone distribution, shipped with guava
- May conflict with the version of guava vanilla uses
We're taking a lot of the experimental API stuff over to FabLabs. It'll be drafted and worked on there before it's PR'd into Fabric API.
Imo fablabs will be large experimental apis that are applicable to previous versions (generally applicable).
Snapshot-bound smaller essential apis like nether biomes or living entity attributes may go through fabric directly, I'd suggest, due to a high necessity.
I wonder how feasable it would be to add an @Experimental annotation, should be able to add warnings to that. IDEA does so for Unsafe and similar things.
Well we could obviously add an annotation in 2s. The issue is IDE support for these annotations so the user can see something.
The user visibility imo can be done with an annotation processor that maybe produces a warning if an annotated class/method/field is used in the abstract syntax tree?
I don't think IntelliJ at least shows warnings from the Annotation Processor in the editing view, I know this because I have gotten Mixin warning that wait to show up until compiling, and then only in the build screen.
All in favor of Jetbrains annotations vote👍 All in favor of literally anything else vote 👎
I prefer JetBrains, because JetBrains IDEs will give a warning, and everything else can be configured to do so easily (or does so by default). Whereas anything else, will not be supported by literally anything.
We need to decide on one annotation standard for ALL projects. This includes yarn, loom, api and loader.
The choice we make imo should be able to support type annotations such as
Foo<@Nullable Bar> and Foo.@Nullable Bar
I think you should talk about the different options and the pros and cons before starting a poll like that.
https://github.com/FabricMC/fabric/issues/499#issuecomment-591084968 https://github.com/FabricMC/fabric/issues/499#issuecomment-591072930 also most the other comments in this issue are that
This isn’t the right issue for the null checking annotations either. I’d create a new issue about it.
I mean JetBrains annotations "just work", while other annotations will be more descriptive. @Deprecated doesn't make that much sense, but will show a warning, while @Experimental makes sense, but no warning in the IDE. I prefer having IDE warnings.
Deprecated was chosen as it works in all IDEs not just idea. Java it’s self was using it (I believe the latest version does something else now) for its own experimental APIs so it seemed a great fit.
@sfPlayer1 Now that we are on java 16, a notable new feature is that @Deprecated now has a forRemoval boolean field. Should we start using those in fabric api now?
I think so, see https://openjdk.java.net/jeps/277 - "the API is experimental and is subject to incompatible changes"
See #1459 where I add forRemoval for apis that are definitely getting removed in the future.
Meanwhile, for actual experimental apis, I suggest a new review mechanism:
We do not need as throughout review for new-generation apis. We would instead add them with @ApiStatus.Experimental and @Deprecated, and have the review for normalization of new api in another pr (we can object or change an api to be forRemoval=true there).