Generating since tags for members

[liach]

Context

Source

haykam — Today at 8:55 PM How would you feel about a @since tag automatically added based on when the intermediary was added? It might be more annoying to have it on every field or method, but definitely on every class since those rarely get mismatched Chocohead — Today at 9:02 PM If you could generate it in the published Javadoc for everything but only classes in the source that would be a good middle ground It'd be useful on methods and fields when you need it but annoying when you didn't

We are seeking to introduce @since tags for elements to indicate from when did they start appearing in intermediaries.

To accomplish this, the main difficulty is to have a system for indexing the start of appearance effectively, as currently these data have to be obtained by checking every intermediary tiny file, and it's not quite realistic to do that every time we build yarn locally.

My plan is to make a tracker for every existent intermediary number in yarn or intermediary. But only tracking numbers is not enough, as we want to record when an unobfuscated name has appeared in Minecraft as well.

Once this data is properly collected, rendering them is no big deal.

cc @haykam821 @Chocohead

[liach]

@sfPlayer1 What way do you recommend so we can find out the introduction version of these intermediaries? Note that tracking counters may not be the most feasible when we encounter non-obfuscated names, which are not accounted by the intermediaries.

[liach]

@modmuss50 Should we implement this feature? If yes, which way do you recommend to implement it so it's not performance/resource intensive? Imo checking every intermediary on every build may be a bit too costly, but generating a since table in intermediary repo for every version (intermediary repo is already growing too large, I heard) might have space concerns.

[modmuss50]

I think it would be nice to have in the javadoc, but generating and storing that info is going to be a bit of a effort. The ovious solution to me would be to clone the intermediary repo when building yarn and run a tool over it to generate the info. I think we can make use of github actions caches to keep the clone time minimal, I dont imagine such a tool being that slow to run?

The yarn javadoc building is already really slow I wonder if there is anything that can be done to speed that up?

[liach]

Can we make a "sinces" file that is updated with each yarn version? So when elements are lost, they are lost in the since file; otherwise, the new ones are added to a new version. Imo keeping such an extra table in yarn repo would be the most feasible (size around that of a built tiny mapping, I think)

In addition, we can consider generating "new api" page to help understanding minecraft updates. This is a new functionality for java 17. https://github.com/openjdk/jdk/commit/dc6c96bbaf1c0af3eacaa2e59646ed7c5bb0767d

[sfPlayer1]

At some point I want to introduce

• UIDs for everything, contrary to intermediary they are meant to change (new links from matching other version pairs, matching fixes)
• version bounds for names and comments to indicate where a typical "equivalent use" method match doesn't translate well to the name/comment (think World.getBlock <-> getBlockState between 1.12 and 1.13)
• automated tooling to backport and maintain names+comments based on the above

Currently intermediary is the best approximation of such UIDs, so we'd use them, but everything should keep the above plans in mind with its design decisions.

Before thinking about a DB, which would essentially act as a cache, I'd try the direct approach of scanning all intermediary mapping files with a small Java program - maybe it's plenty fast. If it happens to be too slow, a tool-local on disk cache should work fine.

[liach]

If we have such a UID system, tracking initial versions are naturally easy as we can add that as one of the data associated to each UID.

For now, my proposed solution is to use that sinces file, which imo is minimally costly. I can probably work on that.