Change Mod Version and Artifact Title

[gabizou]

We've reached a point where it's time to clean up our versioning scheme, not just for SpongeForge, but for SpongeAPI, SpongeCommon, SpongeVanilla, and SpongeForge. Since the issue originally started with SpongeForge needing a version string improvement, the discussion illuminated that version schemes all across the board need to be fixed.

What we have right now

We have versions based heavily on the most current SpongeAPI mentioned in the implementation, which usually is whatever is the latest commit on stable branches.

Latest

Project	Version
SpongeAPI	7.2.0-SNAPSHOT
SpongeCommon	7.1.0
SpongeForge	1.12.2-2705-7.1.0-BETA-3447
SpongeVanilla	1.12.2-7.1.0-BETA-117

Recommended

Project	Version
SpongeAPI	7.1.0
SpongeCommon	7.1.0
SpongeForge	1.12.2-2705-7.1.0-BETA-3361
SpongeVanilla	1.12.2-7.1.0-BETA-59

Why is this a problem

Where to start....

• Identification
  • We can't differentiate between recommended builds, except by build number, which varies on SpongeForge and SpongeVanilla. As seen above, The current recommended (as of writing) of SpongeForge is 3361, and SpongeVanilla has 59. Nothing really else to tell us something different for either project, how many recommended builds we've had.
• SpongeAPI dependency versions
  • Normally, when we make a SpongeAPI minor release, we submit a commit to do the API version bump on all implementations, and then make another commit to bump the API dependency reference for the next incubating API minor version (which again, at this writing is 7.2.0-SNAPSHOT.
  • There's no differentiation whether SpongeAPI 7.2.0 is actually released compared to when 7.2.0 is still in development. Implementation is "implementing" whatever the API is at the commit, but those additions can not only be mostly ignored from a server admin perspective, it complicates the issue of saying that an implementation supports a particular API release in it's fullest compared to previous builds referencing the snapshot version of said api (A SpongeForge build using SpongeAPI 7.1.0-SNAPSHOT from three months ago will be missing some API additions we have made within those three months, and therefor violate the contract that it's not actually implementing SpongeAPI 7.1.0).
• What is BETA?
  • Yeah... let's just drop the useless tag.
• Plugins depending on SpongeCommon
  • Plugins that are implementation aware and may need to depend on a particular implementation variant of not just SpongeAPI, but also the recommended build for possibly a fix or something very much related to the code existing in SpongeCommon
  • We don't have a plugin container for representing the Sponge platform and SpongeVanilla and SpongeForge containers currently take the place of sponge. SpongeCommon needs to start dictating not just the SpongeAPI version, but also the recommended common build version. If we're making modifications to SpongeVanilla or SpongeForge that is irrelevant on SpongeCommon, that's where build numbers can come in to play, and of course, a recommended build would be bumped in common.
• SpongeAPI doesn't use patch versions
  • We did maybe three times, way back when it didn't matter. Since the API has almost no more implementation contained within it, it's now rendered useless.

With these issues, it has made it incredibly difficult to not only teach users to read versions, but also to make it clear when experimental versions are really experimental in comparison.

What do I propose

I'll put up the format equivalent as above for easier comparison:

Format

Project	Format	Comments
SpongeAPI	{APIMajor}.{APIMinor}(-SNAPSHOT)	Remove patch version,
SpongeCommon	{MC}-{LatestAPIMajorRelease}.{LatestAPIMinorRelease}.{RecommendedVersion}(-SNAPSHOT)	Add MC. Use only the latest released SpongeAPI version. Recommended is explained further below
SpongeForge	{MC}-{ForgeBuild}-{APIMajor}.{APIMinor}.{RecommendedVersion(-RC{BuildNumber})}	Since we can't use snapshots in artifact versions for SpongeForge or SpongeVanilla to differentiate, we have to just use build numbers and replace -SNAPSHOT with -RC{BuildNumber}
SpongeVanilla	{MC}-{APIMajor}.{APIMinor}.{RecommendedVersion(-RC{BuildNumber})}	Same as SpongeForge

Example

Project	Latest	Recommended
SpongeAPI	7.2-SNAPSHOT	7.1
SpongeCommon	1.12.2-7.1.5-SNAPSHOT	1.12.2-7.1.4
SpongeForge	1.12.2-2705-7.1.5-RC3447(RC: Release Candidate)	1.12.2-2705-7.1.4
SpongeVanilla	1.12.2-7.1.5-RC117	1.12.2-7.1.4

• Under the example that we have had 4 Recommended builds of SpongeForge/SpongeVanilla and we're working towards our 5th Recommended Build. RC meaning Release Candidate

Wait, so SpongeAPI is changing?

Partially... Since we're going to be dropping the patch version from implementation versions, SpongeAPI version 8 may as well drop the patch version officially (since SpongeAPI has releases with the patch version currently, we have to break it on the major version).

Ok, what's this RC stuff and snapshot?

Glad you asked. RC stands for Release Candidate. If we have a Recommended Build, we'll be actively committing a build as a recommended version, with the actual recommended version bump being made to SpongeCommon. How this changes from current workflows is that we have several builds of both implementations, SpongeForge and SpongeVanilla, which could be considered candidates for recommendation, but when we do make the conscious decision to mark a build as recommended, we do it after the fact. Because we are doing the marking after the fact, we don't have a chance to rename the files any differently, make any tags, commits, etc. except some manual labor of writing some posts and release notes, but no actual version changes for developers to use.

So, instead, we're making the conscious decision that SpongeCommon is comfortable and has enough bug fixes etc. since the last Recommended Build, we'll change the RecommendedVersion in a settings file, and then make the necessary commits bumping the references in SpongeForge and SpongeVanilla. This way, it's very clear that a new build is a recommended build after some testing. In combination with the actual versioning of SpongeCommon, plugin developers will be able to *actually depend on a particular SpongeCommon version that would be shared between SpongeVanilla and SpongeForge! But wait! There's more!! Because SpongeCommon is now being versioned, SpongeCommon is now represented with a PluginContainer, and therefor a valid checked dependency to both Sponge implementations, Forge, (pending these versioning changes) Lantern, and Ore!

Wait, two things: What does SpongeCommon get as an id? And what's this snapshot and RC number for SpongeForge and SpongeVanilla?

Valid pair of questions, I didn't get to really finish talking about the complete PluginContainer aspect of SpongeCommon, but I can now.

SpongeCommon as a project is a bulk of the implementation of SpongeAPI targeting a particular version of Minecraft. What the project originally started as was the Forge implementation of SpongeAPI, at which, the original project's name was just Sponge. Because of this legacy, we've listed SpongeForge and by default, SpongeVanilla as sponge plugin containers. Being that implementation dependent plugins were being written to use the only plugin id to say they depended on was sponge, which brings the problem with Ore, where plugins can't be determined if they depend only on SpongeCommon, SpongeForge, or SpongeVanilla, or a combination of the three (multi-module). Since 90% of our implementation is defaulted by SpongeCommon at this point, and most all implementation dependent plugins already target SpongeCommon, it's safe to just say that SpongeCommon being represented with a PluginContainer with the id sponge is the best option. Likewise, having SpongeCommon having a PluginContainer, the version provided by the examples above makes the version that plugin authors have to reference being platform independent! They don't care if you're running SpongeForge or SpongeVanilla! They only care that you are running sponge with version 7.1.4, because that's what they built on.

And the RC numbers?

Wrong question. Here's the thought process so far:

1. SpongeAPI dropping patch version
2. SpongeCommon getting to use "patch version" for Recommended Version with full -SNAPSHOT support for dependency resolution
3. SpongeCommon having a represented PluginContainer due to versioning
4. SpongeCommon getting the "plugin id" sponge

The better question is: What does this change for SpongeForge or SpongeVanilla?
Answer:
SpongeForge and SpongeVanilla will always have referenced build numbers in between recommended builds, so we need a way to represent that clearly, given that SpongeCommon already tells us what the current core version (7.1.5-SNAPSHOT as an example), while keeping build numbers in play for determining what bugs were fixed between which builds, etc. Because Maven replaces -SNAPSHOT with a timestamp by default, we can't rely on -SNAPSHOT being usable for versions, let alone for build numbers. So, we do some fancy "is this a snapshot or release" detection and boil down the results to this:

If SpongeCommon version is a release version (read, no -SNAPSHOT)
  We are a release version, use the same version string from SpongeCommon
If SpongeCommon version is a snapshot
  We are in development, replace -SNAPSHOT with -RC{BuildNumber}

Leading to the ability to say just from reading a version string: Is this build recommended?

Version	Is It Recommended?
1.12.2-2705-7.1.5-RC3447	No
1.12.2-2705-7.1.4	YES

Wait, what about API versions that haven't been released? How does this resolve that issue?

Ah yes, almost forgot. Unreleased APIs are a little troublesome. Since we only take the {APIMajor} and {APIMinor} version as a partial version for showing what SpongeAPI is supported (fully), we have to somehow show that a major SpongeAPI version is still incubating (bleeding) and hasn't been released. To do that, we consider the SpongeAPI version reference I made in the format above, {LatestAPIMinorRelease}. Since in-development major versions of SpongeAPI have never had a release, let alone a minor version release, the implementation is equally still in development. That being said, the solution is to simply "reset" the RecommendedVersion back down to 0-SNAPSHOT, leading to the following SpongeCommon version: 1.12.2-8.0.0-SNAPSHOT, which leads to this example from a pre-existing SpongeForge version: 1.12.2-2705-8.0.0-RC3449.

Hold on, if unreleased API versions have 0-SNAPSHOT, how do we know when there's an official release of the implementation supporting the just released 8.0 SpongeAPI?

Yep, I know, it's a little quirk, but remember, we use -SNAPSHOT to represent a goal towards next release of that target number. The workflow when a new SpongeAPI major release occurs, and SpongeCommon, SpongeForge, and SpongeVanilla are recommended for use of the full API available with that major release version, we can just make a formal release without the -SNAPSHOT identifier. This would lead to (as an example again): the first release of SpongeCommon supporting the full release of SpongeAPI having the version 1.12.2-8.0.0. Here's a table example:

Project	Bleeding-In-Dev	First Release	Build After Version Bump (back to snapshots)
SpongeAPI	8.0-SNAPSHOT	8.0	8.1-SNAPSHOT
SpongeCommon	1.12.2-8.0.0-SNAPSHOT	1.12.2-8.0.0	1.12.2-8.0.1-SNAPSHOT
SpongeForge	1.12.2-2705-8.0.0-RC3449	1.12.2-2705-8.0.0	1.12.2-2705-8.0.1-RC3453
SpongeVanilla	1.12.2-8.0.0-RC117	1.12.2-8.0.0	1.12.2-8.0.1-RC120

From this table, we can now easily see what the first major release will look like, what in-between releases will look like, how recommended builds will be versioned, and lastly, make recommended builds easily identifiable.

Summary

SpongeAPI Changes

• Drop Patch Version. We don't need to break old version numbers, just break new ones. SpongeAPI 7.2.0 may well be the last one to have such a number (if we don't choose to change it after this issue is settled)
  + Useless feature that previously just occupied an extra two characters
  - Incompatible with previous regex version strings. Other projects may need to drop support of features for older versions.
  + Because this is still a new version, it's a simple range detection.

SpongeCommon Changes

• Adopt {RecommendedVersion} with SNAPSHOT support. The whole version is constructed with the format: {MinecraftVersion}-{APIMajor}.{LatestAPIMinorRelease}.{RecommendedVersion}
+ SpongeCommon becomes a properly versioned dependency for plugins
  + Maven support. Releases are easily detected, and likewise snapshots are updatable.
  + {RecommendedVersion} reset on {APIMajor} bumps (bumping from SpongeAPI 7.x to 8.x will need to have the {RecommendedVersion} set back to 0-SNAPSHOT).
• Provide SpongeCommon with a PluginContainer. This is to be able to represent SpongeCommon separately as a depdency from SpongeForge or SpongeVanilla.
  + Plugins depending on sponge will be able to depend on a particular recommended version or higher, as supported by Maven
  + Platforms like Lantern can easily detect if a plugin is depending on SpongeCommon's implementation before attempting to load the plugin.
  + Ore can tag plugins automatically for platform support.
  - Plugins believing sponge being SpongeForge and using forge related classes will now fail, but who cares? They need to update anyways.
  - Previous dependency references for a SpongeCommon version will break, but who cares?

SpongeForge Changes

• Drop BETA tag.
  + Was a useless tag anyways.
• Format version according to SNAPSHOT or RELEASE status. If this build is a snapshot recommended version, replace the -SNAPSHOT with -RC{BuildNumber}. If it's a release, don't change the version.
  + Still showing what Forge version we depend on
  + Easy viewing of whether someone is running a recommended build or not
  - Each build is still considered a maven release since the version string is unique.
  + Can filter builds for being recommended or release candidate builds.
• **Adopt spongeforge as an id to represent SpongeForge's PluginContainer. This is out of necessity since we already have to represent SpongeCommon, we need to present an equally appropriate PluginContainer for SpongeForge
  + Plugins can specifically depend on SpongeForge, and particular version ranges.
  + Ore can tag plugin releases for platform dependencies just by the contained plugin containers
  - One more PluginContainer representation to implement

SpongeVanilla Changes

• Drop BETA tag.
  + Was a useless tag anyways.
• Format version according to SNAPSHOT or RELEASE status.
  + Similar to SpongeForge, except the missing Forge build number dependency.
  + Aside from the build number, the version will match SpongeCommon exactly on releases.

I've encouraged the discussion to get to this finalized version. I would encourage any issues with the new format to be brought up soon before the final decision is made.

[ryantheleach]

I really really welcome the changes regarding the SpongeAPI versioning, as it will greatly simplify Ore dependency requirements, and education of users.

That said, I'm not sure how difficult it is to actually implement it gradle wise.

As long as stable and bleeding remain separate, I don't foresee any issues with the versioning string confusing dependency resolvers either.

The only difference I would potentially make, is label Experimental/Bleeding builds more aggressively.

spongeforge-1.12.2.2705-8.0.0.23-PRERELEASE.jar would represent API8 on bleeding, before any recommended builds, using PRERELEASE as opposed to snapshot, for end users benefit.

If problems occur regarding needing SNAPSHOT for dependencies, maybe this could only be exposed this way on the downloads page, and the repo's would continue to use SNAPSHOT, and SNAPSHOT for the actual versioning.

[XakepSDK]

Maybe from least changing values to most changing?
spongeforge-1.12.2-7.0-2705-4.12.jar

[dualspiral]

I think this is reasonable. Thoughts are below (I don't know how I can write so much about versioning...)

Removes the "hot fix release" number from the API version string, since it's not used

Yep - I'm trying to work out where we might use a patch version, other than JD clarifications and deprecations I don't see it. Besides, having yet more release branches is just going to sap even more of our limited time. I am completely for this change. Would this work its way back to the API versioning too, or is this just SF (and probably SV)?

...{SpongeAPIMajor.SpongeAPIMinorLatest}.{RecommendedBuildNumber}.{NumberOfBuildsSinceLastRecommended}

It's fine as is, though I do wonder if people are going to see 7.1.5.20 as more recommended than 7.1.5.0 which we actually mark as recommended. Not sure I have a specific change to propose with that though, I don't really think we want to start adding -BETA on to all non-recommended builds!

This thought is probably better solved by making recommended builds more prominent on the Downloads page (and latest builds less prominent), that's a separate issue that I know is having separate discussions.

The only difference I would potentially make, is label Experimental/Bleeding builds more aggressively.

One thought I had on the bleeding branch is to just not give it a version number (somehow) to further discourage its use as a bleeding version. I'm not completely sure as to how to do that, maybe just replace the API + Recommended version number with BLEEDING in such builds?

spongeforge-1.12.2.2705-BLEEDING.xxx.jar

The more we can discourage those builds, the better. I've seen plugin authors actively advertise their plugins for the as of writing unreleased and hugely unstable API 8 which really, given the state it's in, they shouldn't be doing. They are giving the idea that API 8 is ready when it is far from it (their plugins are going to break so much when our big changes land), based on the number of people suggesting they are using 8.0.0 builds anything we can do will help in the long run.

[Mumfrey]

I think it's worth bearing in mind that the -SNAPSHOT suffix isn't arbitrary*

* edit to clarify that this is obviously when the artefact is available via a maven repo.

[ryantheleach]

If problems occur regarding needing SNAPSHOT for dependencies, maybe this could only be exposed this way on the downloads page, and the repo's would continue to use SNAPSHOT, and SNAPSHOT for the actual versioning.

[Mumfrey]

Sorry @ryantheleach I didn't see your reply.

[stephan-gh]

I discussed this with @gabizou yesterday and we have already established that the new versioning scheme requires marking recommended builds before they are built, not some time later, e.g. by bumping the recommended build number in gradle.properties. Otherwise there is no way to determine the {NumberOfBuildsSinceLastRecommended} for all other builds. This also allows us to properly tag them on Git (like for the API).

As for how to determine {NumberOfBuildsSinceLastRecommended}, we discussed 3 possible options so far:

• Use Jenkins build numbers. We cannot "reset" the Jenkins build numbers with each recommended build, as it stores all information (e.g. logs) about previous builds based on their build numbers.

  ? We would need to store the "real" build number of the last recommended build somewhere to get CurrentBuildNumber - LastRecommendedBuildNumber = NumberOfBuildsSinceLastRecommended.

• Use git describe to determine the number of commits since the last tag and use that as a build number. This would more make it a {NumberOfChangesSinceLastRecommended}.

  + Easy to determine from Gradle, without storing any additional data as counter.
  - Sometimes there will be large jumps (e.g. after a branch was merged)
  - How to handle bleeding? There are no tags on the bleeding branch. A possible solution would be to create a tag before stable is branched.

• Use Maven's SNAPSHOT mechanism to provide build numbers.

  + Like for SpongeAPI, there would be releases ("recommended builds") and snapshots to consume as Maven dependencies. (This is much cleaner for plugins building against SC/SV/SF...)

  + The download indexer can automatically promote all Maven releases as "recommended". (This functionality already exists for SpongeAPI)

  - We have less control about the version format: Maven replaces the -SNAPSHOT suffix with a timestamp and a build number, so the actual filename of a non-recommended build would be spongeforge-1.12.2.2705-7.0.4-20180101.081453-1.jar. We can display this differently on the downloads page, but the filename would be like that.
  ( + This is also an advantage to some extend: It addresses @dualspiral's second thought in the comment above: The filename is long enough to make it clear that it is an experimental snapshot, and not a newer recommended build.)

  ? The timestamp and build number in the version is determined when the build is uploaded, not while it's built. Therefore /sponge version would only display -SNAPSHOT by default. I've been thinking about querying the Maven repository before the build, though, so it might be possible to avoid this.

[phase]

How to handle bleeding? There are no tags on the bleeding branch.

Why can't the bleeding branch have tags? Isn't it being changed to api8 anyway?

[ryantheleach]

@phase No reason it can't it would just be slightly (but not very) unorthodox, and would either require automation, or strict adherence to remember to tag.

A possible solution would be to create a tag before stable is branched.

Was mentioned by Minecrell.

Also, unless Bleeding has a separate versioning thing that is kept separate, having those extra tags could also potentially interfere with the bleeding versioning numbers? Or at the least 2 solutions would be required?

That's how I understand it anyway, Minecrell could probably refute or validate it.

[stephan-gh]

Why can't the bleeding branch have tags? Isn't it being changed to api8 anyway?

Bleeding as the work-in-progress branch of the next API version shouldn't have any releases. That doesn't mean it cannot have tags though, as those don't have to be releases.

[gabizou]

@Minecrell any luck on getting some of the versioning we discussed working?

If I recall correctly, we have it where it's {MC}-{ForgeBuild}-{APIMajor}.{APILastMinorRelease}.{RecommendedBuildBumped}.{BuildSince}?

[stephan-gh]

@gabizou Haven't really worked on it. We still need to make a final decision for one of the options I posted above, all of them have disadvantages so we just need to pick one of them.

Right now the one that looks easiest to implement is the git describe option (see above), but it doesn't really have "build numbers", it only provides "commit numbers".

A Maven snapshot compatible versioning was my favorite, but after additional investigation of possible options and the Gradle/Maven source code, I haven't really found any nice way to integrate it properly.

[mbax]

How about we make it so the user doesn't have to visit the docs to figure out what they're looking at? MC version first (user cares most), Sponge RB and build number (whether builds-since or total-builds, that's separate from my proposal) next, and finally anything extra (like forge version).

• spongeforge-MC1.12.1-RB1-build3361-forge2705.jar
• spongevanilla-MC1.12.1-RB1-build59.jar

Users should not need to care about API version. Simplify it down to MC version and RB number, with API versions released on RB release.

[phit]

while I like this format from a userfriendliness perspective, what happens when a mc version has multiple api versions?

[mbax]

while I like this format from a userfriendliness perspective, what happens when a mc version has multiple api versions?

"...with API versions released on RB release."

spongeforge-MC1.12.1-RB2-build3485-forge2705.jar

Educate users that a plugin only runs on the latest RB.

[phit]

okay that doesn't really answer my question, sorry I wasn't quite clear
what do you name the jars for api versions that dont have a rb?

[mbax]

I don't really have a solution to that problem :D

The first post in this issue also seems to just include the RB number regardless of being the recommended build or not.

Perhaps using a builds-since-RB strategy would better clarify, with build 0 (or build number removed) as recommended build and then counting up on something that communicates it's after the RB.

[dualspiral]

How will that work for plugins and third party implementations, such as Lantern?

The reason we have an API version is so that we can say “this plugin runs anywhere that implements API 7”. I get this is about implementation, but the SpongeAPI is wider than just SpongeForge and SpongeVanilla (that might see different RB numbers depending on how the impl matures). By educating users that the plugin only runs on a particular RB might indicate incorrectly that it only runs on SF or SV, or even just one of these. It might also encourage users to stay with an outdated RB. Lantern could implement API 7 on the 1.13 protocol if it so chooses (though I seriously doubt they would) - an API version is (theoretically) separate from the version it runs on.

It’s also important to note that it isn’t necessarily one-for-one with major API releases and Minecraft versions. We may need to break the API and release a new major version mid Minecraft version cycle - how would be convey that then?

I get that this sucks with API versioning and impl versioning and I understand comments about users caring more about MC version over SpongeAPI version, but I’m not sure that we should hide the API version altogether because it’s that what guarantees compatibility, NOT the minecraft version. If we can find a way forward that encompasses the entire SpongeAPI ecosystem, great!

[ST-DDT]

IMO the API version has to be part of the name/version suffix.
I would go as far as saying that the current way of referencing the API is almost perfect. It only needs an indicator that it refers to an API preview of the next release. (I don't care whether we limit the API version to 2 parts or not)

Example:

• spongeforge-PRE7.2.0-...4000.jar
• spongeforge-7.1.0-...3661.jar

This has the following advantages over referencing the last released version.

The version numbering is more consistent with new major versions. Lets assume we would be working on API 8.0 right now. How would the SF jar be named? After the last released API version (=7.1.0)? But 7.x and 8.0 are incompatible (otherwise we wouldn't have to use a new major version in the first place). So we have to stick to 8.0 as an identifier. But 8.0 hasn't been released yet so we need to clarify that (by using a special prefix like PRE). But if we need a prefix for one version we can use it for every version. This would also allow server administrators to verify whether the newly developed plugin for API 7.2.0 can (potentially) be run on the server version spongeforge-PRE7.2.0-....jar they just have downloaded.
(Instead of PRE we could also use something else like BLEEDING or SNAPSHOT)

---

As for the other parts: @gabizou 's suggestion looks good to me.

[gabizou]

To summarize the issue:
API version is required
Minecraft version is required
Signifying an implementation is depending on a bleeding API required
Forge build version required (though Forge may be changing version strings, pending some discussion with forge peeps)

Since we can't get maven publishing to auto increment builds, but we can get some git-fu tasks to "calculate" the amount of builds since a recommended, we could very well keep with having RB in the name to signify whether this is based on a recommended build yet or not, so for example:

gradle.properties {
  recommended-version=3.0-SNAPSHOT
}

Artifact name:
spongeforge-{MCVersion}-{ForgeBuild}-{API}-RB{RecommendedNumber}.{Build}.jar -> spongeforge-1.12.2-2705-7.1-RB3.0-SNAPSHOT.jar
With the version string:
{MCVersion}-{ForgeBuild}-{API}-RB{RecommendedNumber}.{Build} ->
1.12.2-2705-7.1-RB3.0-SNAPSHOT

What we could even do is if we wanted to keep build numbers relative in the string for artifacts (only because recommended builds are recommended and could very well be tagged and made formal releases by maven), the build number can be included in the recommended build string like so:
RB3.0.3440-SNAPSHOT to further signify that

• It is still a snapshot, in development, testing, bug fixing, not a formal release
• Still reference able as a build number for bug reporting and verifying bug fixes
• Recommended builds drop the build number in their version string because they're recommended builds, and we can refer to them simply as RB3.

What we also gain the benefit of is that if we need to make a bug fix release of a recommended build, we can bump the minor version of the recommended version (so 3.1) as necessary.

I feel with this approach, we could very well preemptively define recommended builds on a normalized release schedule (not that we'd keep to it anyways) without having to mark older builds as recommended after the fact.

@Minecrell let me know if this seems feasible as I want to get this issue sorted and implemented for 1.13's development and quite possibly start 1.12 builds on the new format. It won't be a flip of the switch, we'll have PSA's on the forums etc., but it's something I'd rather we get done instead of letting the issue get tossed back and forth for months.

[ryantheleach]

@gabizou Your latest reply seems ambiguous to whether 7.1 represents a released API version, or the current 'snapshot' version. This is arguably the most important point to me, and plugin devs being nagged by server admins on Ore.

@ST-DDT

I would go as far as saying that the current way of referencing the API is almost perfect.

I would go as far as saying that the current way of referencing the API is terrible, causes undue pressure on plugin authors to 'update' to bleeding API before it's released, releasing plugins which, will break, should API be adjusted before release. This is the root issue to all the plugins depending on the latest snapshots, falsely believing that this makes them 'compatible' with the latest Sponge builds, as opposed to releasing test builds.

[gabizou]

@gabizou Your latest reply seems ambiguous to whether 7.1 represents a released API version, or the current 'snapshot' version. This is arguably the most important point to me, and plugin devs being nagged by server admins on Ore.

I'd say what I said before (I wrote my example as 7.1 because that's the most current released version), decrease the API minor version if it has not been released yet (or if the minor version is already 0 and we're still in SNAPSHOT, means we're on a bleeding branch, and then the PRE is applied in replacement to RB), leading to say that we have guaranteed support for that API release (and plugins building against that API are going to work), whereas plugins depending on the latest and greatest minor API additions would likely have to somehow explicitly mention what build they depend on, maybe. The last bit about plugins depending on latest and greatest snapshots is hard.

[phase]

I would go as far as saying that the current way of referencing the API is terrible, causes undue pressure on plugin authors to 'update' to bleeding API before it's released, releasing plugins which, will break, should API be adjusted before release.

I want to back this up with the Ore perspective. Ore is flooded with people using snapshot APIs, and it's greatly in part to how we market our API versions. This is bad for server owners who are wanting to look for something that matches their setup. An API & MC Version filter will be coming soon, but having people depend on these unstable APIs is inherently bad!

[gabizou]

Posting here again with some additional refinements and clarifications regarding recommended builds of implementation (and resolves versioning sponge common to be maven usable and ore definable):
This is a readme document to specify what sort of versioning standard Sponge will be adopting moving forward.

Currently, we have the following (all projects versioning currently):

SpongeAPI:

Maven style version, Currently at 7.2.0-SNAPSHOT. There's additional information provided for the commit marking the build (for changelog/indexing) that is included in the meta, but not part of version strings. This portion is not going to change (may drop the bug fix version and just have major.minor).

SpongeCommon:

Maven versioned based on the API target, not versioned in any other way to artifacts. This needs changing. Currently, we have a cycling release of API 7.1.0 builds of SpongeCommon as bugs are fixed towards the next Recommended Build.

Current:

Type	Format	Example	Explanation
Maven Version	{API}	7.1.0	This is built on sponge api.
Specification-Version	{API}-{commithash}	7.1.0-ff990df4	Includes the commit hash of the API for /sponge version
Artifact Name	spongecommon-{API}	spongecommon-7.1.0-dev.jar	Same as maven version, does differentiate for api snapshots, but not for sponge common snapshots, no reference of "recommended".

Changes:

Type	Format	Example	Explanation
Maven Version	{MC}-{APIMajor}.{APIMinor}-{RBNumber(-SNAPSHOT)}	1.12.2-7.1-RB4-SNAPSHOT	We don't have build numbers on sponge common, we can for SV and SF. SpongeCommon being the common dependency however, allows us to use maven style dependencies just fine.
Artifact Version	''	''	Same as maven version, no real need for differentiation for the artifact name, except of course adding spongecommon.

SpongeForge:

The whole kaboodle of information.... This needs to be clear from an artifact name and from in game version string presented that we can pinpoint which version is being used.

Current

Type	Format	Example	Explanation
Maven Version	{MC}-{ForgeBuild}-{API}-BETA-{BuildNumber}	1.12.2-2705-7.1.0-BETA-3447	This is to make it simple to find out multiple things: Minecraft required, Forge required, what API this is implementing, and what build number of SpongeForge this is. All bits are important, but API specifically targets whatever the current dependend API version string is, regardless whether the API is incubating, bleeding, breaking, etc.
Implementation Version	Same as above	Same as above	No differentiation between implementation version, version, and maven's version.
Artifact Name	spongeforge-{MC}-{ForgeBuild}-{API}-BETA-{BuildNumber}	spongeforge-1.12.2-2705-7.1.0-BETA-3447	A literal prefix of spongeforge added to the maven string.

Problems with this

For starters, we have to manually promote recommended builds after the fact, and there's little way of knowing if a spongeforge is a recommended build or not just by running it or looking at the version string. People know recommended builds by build number.
Likewise, because each build of SpongeForge is a new version string number, there's releases for each build of SpongeForge, leading to developers potentially targeting only a specific build number or using +, but again, not knowing if something is recommended or not.
Additionally, it's impossible for server owners to know whether a plugin will work on an implementation without manually testing, because plugin developers potentially targeting incubating features may have only been added or implemented more recently than the running build of spongeforge (api version representation issue).

Changes

Type	Format	Example	Explanation
Maven Version	{MC}-{ForgeBuild}-{APIMajor}.{APILatestMinorRelease}-RB{RecommendedVersion(.BuildNumber-SNAPSHOT)}	1.12.2-2705-7.1-RB4.3447-SNAPSHOT	Drop BETA, not needed. Still identifies Minecraft and Forge. Now identifies API releases for implementation, not API snapshots, optionally includes build number if not a recommended/release build, determined by gradle properties (include or don't include -SNAPSHOT)
Implementation Version	Same as above	Same as above	No differentiation between implementation version, version, and maven's version.
Artifact Name	spongeforge-{MC}-{ForgeBuild}-{APIMajor}.{APILatestMinorRelease}-RB{RecommendedVersion(.BuildNumber-SNAPSHOT)}	spongeforge-1.12.2-2705-7.1-RB4.3447-SNAPSHOT	A literal prefix of spongeforge added to the maven string.

The point I'd like to emphasize here is the Recommended Build idea:
When we have a recommended build to commit (this would be applied to SpongeCommon, which a bump to the
git submodule reference would bump SpongeForge and SpongeVanilla), the RecommendedBuildVersion would be numbered as a release like so:

RecommendedVersion=4

Leading to the following version string:
1.12.2-2705-7.1-RB4

Alternatively, if it's not a recommended build, it'd be like so:

RecommendedVersion=4-SNAPSHOT

Leading to the following version string:

`1.12.2-2705-7.1-RB4.3447-SNAPSHOT

The build number MUST be included, since that is still a definition for a lot of people about bug
fixes in between recommended builds, but the SNAPSHOT addition would further identify the build as
not being a recommended build. This also allows us to start referring people to recommended build numbers,
instead of actual build numbers (easier to say "Use RB4, instead of 3447" and easier to visually see the
version number difference on the downloads page, etc.).

Likewise, this will further identify bleeding builds as the RecommendedVersion would be set to 0
and the version string being:

1.12.2-2705-8.0-RB0.3447-SNAPSHOT

Which brings the visibilty that the API has not been released, nor has there been a recommended build
of the implementation for said unreleased API. As with all API releases, the first API release will
always need a good recommended build of implementation to follow and signify "it's ready".

Note that RecommendedVersion will always need to be reset on an API major/minor version release.

[gabizou]

@SpongePowered/developers @SpongePowered/docs @SpongePowered/ore Updated the original description of the issue for a more finalized proposal. Please bring up any issues or comments for changes as the format will be final very soon.

[gabizou]

Having discussed it with Zidane, we're deciding the issue description in OP is the final format.

To summarize, the new format is:

Project	Format	Comments
SpongeAPI	{APIMajor}.{APIMinor}(-SNAPSHOT)	Remove patch version,
SpongeCommon	{MC}-{APIMajor}.{LatestAPIMinorRelease}.{RecommendedVersion}(-SNAPSHOT)	Add MC. Use only the latest released SpongeAPI version. Recommended version is defined in this project.
SpongeForge	{MC}-{ForgeBuild}-{APIMajor}.{LatestAPIMinorRelease}.{RecommendedVersion(-RC{BuildNumber})}	Since we can't use snapshots in artifact versions for SpongeForge or SpongeVanilla to differentiate, we have to just use build numbers and replace -SNAPSHOT with -RC{BuildNumber}. BuildNumber is defined in the Jenkins build (defaults to 0).
SpongeVanilla	{MC}-{APIMajor}.{LatestAPIMinorRelease}.{RecommendedVersion(-RC{BuildNumber})}	Same as SpongeForge

With the following latest recommended and latest bleeding builds (and future release builds).

Project	Latest	Recommended
SpongeAPI	7.2-SNAPSHOT	7.1
SpongeCommon	1.12.2-7.1.5-SNAPSHOT	1.12.2-7.1.4
SpongeForge	1.12.2-2705-7.1.5-RC3447(RC: Release Candidate)	1.12.2-2705-7.1.4
SpongeVanilla	1.12.2-7.1.5-RC117	1.12.2-7.1.4

Project	Bleeding-In-Dev	First Release	Build After Version Bump (back to snapshots towards next minor release and/or recommended)
SpongeAPI	8.0-SNAPSHOT	8.0	8.1-SNAPSHOT
SpongeCommon	1.12.2-8.0.0-SNAPSHOT	1.12.2-8.0.0	1.12.2-8.0.1-SNAPSHOT
SpongeForge	1.12.2-2705-8.0.0-RC3449	1.12.2-2705-8.0.0	1.12.2-2705-8.0.1-RC3453
SpongeVanilla	1.12.2-8.0.0-RC117	1.12.2-8.0.0	1.12.2-8.0.1-RC120

Naturally, we cannot change previous artifacts in any way, nor their versions, so this format change will still need documentation on the old format just to read legacy builds (?), depending on @Inscrutable's consideration.

I'd very much like for our current stable and bleeding branches to adopt the new format (API 8 builds will adopt new format, API 7 will keep old format, just API, not common or sponge forge). So we'll still have API 7.2.0-SNAPSHOT and 7.2.0 and 7.3.0-SNAPSHOT, but when this is flipped, API 8 will start having only 8.0-SNAPSHOT and 8.0 and 8.1-SNAPSHOT etc.

We should very well close this issue with a commit that officially starts the version change in stable-7.

[Inscrutable]

SpongeDocs can expand the current versioning page to include the new version formatting, retaining an explanation of the old style "Legacy format" and it's deprecation date. Probably also including the first and last builds of each so users can easily see where the change took place.

[ryantheleach]

I have a minor quibble with the UX of the terms RC vs RB, and was in mixed feelings of using the term

Preview, Pre Release, to represent RC instead,

On one hand it would match the semantics of minecraft pre release / experimental builds but apply to us instead,

On the other hand confusion could be had as users believe it's related to the mojang pre releases.

Overall I am extremely pleased with the result (if this is the final version) and I know I've been irritating to talk to about this issue during SPAM and that is IS/will be a monstrous effort to change something that seems rather small. This should make versioning a ton easier for new users to our platform, and stress removed from plugin developers.