Apologies if this has been asked and is answered somewhere (I looked through the pinned posts and API doc, and didn’t find it), but is there a migration guide for the various API versions?
For example, is there something which documents new/changed/deprecated API elements going from API5 to API6, and from API6 to API7?
I guess it sorta would look like a changelog, but organized for plugin devs to quickly see what parts of their plugins have to be changed to migrate to newer API versions.
(If there is something like this, perhaps a pinned post linking to it? Would seem to be a useful resource.)
1 Like
I’ve never thought of it, but I would like something like this as well. Status posts and SOS don’t really do this justice, and the traditional method of ‘fix all the red underlines’ doesn’t address structural changes, e.g. the cause stack change.
It’s never been considered as far as code changes go, what we had intended was something along the lines of comparing change logs on the docs pages as a comparison (assuming the docs would get code example updates between api versions). I just don’t think there’s a good chance the team can officially dedicate that time to make a proper code example change log (though, the test plugins in sponge common is fairly new, it would provide as examples of changes in the future).
Thank you for the quick replies. 
I’ve been looking at various server setups for a while, and settled on Sponge for a new modded server I am working on. The only issue is that plugin development for some useful features seems to stall on various specific projects, and I thought about helping out some. One of the issues is I want to run a 1.10.2 server (due to the mods I want to run still not updated to 1.12), which would be API5, and the plugin development tends to migrate to API6 and API7 with new features/bugfixes only added for those, and not backported. I understand why, from a developer perspective, and intend no harsh criticism over it, but as a pack integrator and server admin, it can be a bit frustrating.
As a result, for some of the plugins which I would like to have, I want to help out by providing some of that. Of course, I am a code newbie (though not a coding newbie 
) when it comes to Sponge, so am reading up on the API doc to see what all I need to do.
I would volunteer to make such a migration guide as I am learning it, but would appreciate any help or pointers towards parts of the documentation which would be most useful in making it.
Absolutely would appreciate all the help we can. To be frank, the primary reasons why back porting bug fixes between API 7 -> API 5 implementations is the massive structural changes that went into the implementation between all major versions since API 5.
While API 5 did not quite have the used to be called CauseTracker PhaseTracker exposed to plugin developers, API 7 introduced the CauseStackManager which was paired with almost a full rewrite of what is now called the PhaseTracker. Along with these changes, as they power virtually all main-threaded events being called and tracked, we did not have the chance to back port any of the more recent changes, especially as some changes are based on code that has been drastically changed structurally and would be more time consuming to re-verify if the bug was even there to begin with.
This does not go to say that it’s possible for someone to write some PR’s to port some more recent bug fixes that could be ported to the older implementation, I’d accept them, but I professionally would not stand by the legacy unsupported builds.
That being said, we did introduce test plugins in development with API 7 implementation testing so that API changes that do affect certain API parts can be “seen” as “how to upgrade”. As there are several plugins, some use some basic features and others can use some more advanced features.
I’d be very much appreciative for any work you put forward to the Sponge project, as it’s progress is always driven by the community. Pinging @Inscrutable to provide the options and maybe docs branch for such documentation planning?
Whilst I’d love to see more docs, we have enough trouble just getting the Plugin pages updated from API5 to API7 - progress has been very slow. We really need more contributors to get on top of this. When that’s done, then some API 5->7 migrating docs might be viable, although how that could be structured will need some deep thought. There are a few related PR’s about updating API references, which is a start…