I’ve been keeping my plugin at API version 4.0.3 as this is the most recent ‘release’ version. Even through the last change that I can see to API 4.1.0 is from 2 months ago I haven’t updated to 4.1.0 because it’s not released and if I were to update, it would make versioning completely pointless as at any time changes can be made without a version bump.
Now I noticed the recommended spongeforge version to download became 1.8.9 - 4.1.0-BETA-1320. And I also noticed a number of other plugins opted to depend on API 4.1.0.
Should I update to 4.1.0? I’d rather not update while it’s not marked as released but… I also don’t want users trying out my plugin for the first time and possibly find it crashing due to the version mismatch (I haven’t checked yet if I’m using any changed methods).
All 4.X API versions are compatible to each other except for some new features in 4.1, so unless you need them it is safe to build against the latest API release because it should run on all 4.X implementations without any necessary changes.
Breaking API changes will always go into a new major version bump (e.g. API 5.0.0)
Oh, I thought additions were like 4.0.X and changes 4.X.X.
What’s the difference between 4.0.X and 4.X.X?
Anyhow thanks, that solves it.
Generally 4.0.X is for hotfixes of 4.0.0 e.g. if there is a bug in 4.0.0 which prevents proper usage of the API version then 4.0.1 is released to fix it, etc.
So API 4.0.X can contain breaking changes for hot fixes? Doesn’t that go against what you said in your first post? Or are hotfixes only additions?
Sorry if I’m being a pain but trying to fully understand so I can depend on the info in the future.
1 Like
Best Practice
If a plugin lists 4.1.0 That should mean they are relying upon features only introduced in 4.1.0 to work correctly, otherwise if they work on 4.0.0 they should list 4.0.0.
If sponge need to release a fix to the API (note that the fix might be inside the classes packaged with the API, and not actually change it’s interfaces that plugins interact with) they will release a hotfix.
If a plugin relies upon 4.0.1 for example, and can not work with 4.0.0 due to the bug, they should list their requirement as 4.0.1, if it’s unaffected by the hotfix, it should list it as 4.0.0
Reality
Granted, that while the above is best practice, in reality it can be a royal pain to test forwards and backwards on multiple versions to make sure that you don’t accidentally rely on some behaviour introduced between versions.
So plugin authors generally disregard the above advice, and just say the version number they are currently built against, This lets the users know the what version the minimum (is most likely to be, it may work on lower versions but not guarantee’d due to lack of testing) and that minor version changes (major.minor.hotfix) should not effect the plugin.
This is further complicated by the fact that this is only the API and theoretical versioning, there are changes that are possible in the implementation that might leak, and require changing between releases, let alone API versioning.
e.g. CreeperMend’s next release will rely on behaviour that was introduced on a specific commit in SpongeCommon, which isn’t exposed in the API, so I will either need to wait until an API bump happens that’s later then that release, or state the minimum requirements for both SpongeVanilla and SpongeForge.
The proper solution is to instead depend on 5.0.0-SNAPSHOT.
2 Likes