Updates for new Versioning Policy#785
Updates for new Versioning Policy#785Inscrutable merged 14 commits intoSpongePowered:stablefrom Grauldon:feature/versioning
Conversation
source/versions/versioning.rst
Outdated
| developers. *SNAPSHOT* is associated with the API, and *RC*, or Release Candidate, is associated with the | ||
| implementation (SpongeVanilla and SpongeForge). | ||
|
|
||
| *SNAPSHOT* and *RC* are **always** associated with a number (e.g., ``1-SNAPSHOT``, ``-RC120``). With *SNAPSHOT*, the |
There was a problem hiding this comment.
1-SNAPSHOT ?
what does that mean, snapshot is a suffix for the whole version before that, you cant just take the patch version by itself.
7.1.0-snapshot unlike RC120 is also not the name for a specific version, its refers to every build between releases.
source/versions/versioning.rst
Outdated
| SpongeAPI is the actual API that allows plugins to interact with the game. However, the API is enabled by the Sponge | ||
| implementation (SpongeForge or SpongeVanilla). Together, these products form the foundation of a Sponge server. | ||
|
|
||
| As such, the version string reflects the state of these two products. The major and minor release components of a |
There was a problem hiding this comment.
I don't agree with this, the implementation does derive part of its version from the API for clarity sake, however the versions are disconnected. 8.0.2 will never be a thing in API and the part derived from the API is 8.0.0 not 8.0.
So a lot on this page does not make much sense to me personally, how it is explained and how you split the version string, but maybe I'm seeing it wrong. We will see what others say, just leave it for now.
Inscrutable
left a comment
Inscrutable
left a comment
There was a problem hiding this comment.
Excellent. I'll see what others have to add to this. We want it to be concise.
|
@Grauldon Thanks for your contribution. Just a note: the stable branch is used for the 7.X.Y version of the docs. |
|
I'll plan to return to this PR this week. My original plan was to balance time between this one and #784 better. Using git stash to rebase with stable has helped me to realize how to accomplish this. Thanks for all of the feedback! |
| @@ -0,0 +1,118 @@ | |||
| ========== | |||
| Versioning | |||
There was a problem hiding this comment.
First, please let me thank you for all the work you've done so far. I do not want to detract from it and this thought process would not exist if you hadn't stepped up, so thank you!
However, this particular page doesn't feel like it's particularly useful in this form. We talk about sem-ver, what it means, then the version string, but because there is so much on here, when you look at the API version string, for example, people may have lost the link to sem ver. It is better to explain what each bit means inline for us.
I think what I say needs discussion (@SpongePowered/docs) and this is just my own opinion, but I would:
- Remove the semver section, with the exception of a tip at the top saying "Sponge follows a format of the SemVer specification in its projects. You can read about general SemVer usage at http://semver.org". There really is no point in us rehashing it.
- Say that SpongeAPI and SpongeForge/SpongeVanilla follow two different versioning policies
- Highlight the important parts of the version string as the semver part and, for impl, the minecraft version
- Explain what that means for the developer (for the API version string) and the server owner (for the impl version string) - most of this page doesn't really decribe that and that's what the versioning is really all about for us.
For the API, it needs to boil down to this:
- A change in the major number indicates that some APIs that were guaranteed in the previous version have been broken. 5->6 broken world pregen APIs, for example. 6->7 was a more significant break. A bump in the major number is always accompanied by resettign the minor number to zero.
- Developers know that their plugins might break when this changes, i.e. API 6.x plugins might not run on API 7.x.
- A change in the minor number (but not the major number) means that API calls have been added, but plugins for previous minor revisions of the same major revision will still work - but this isn't necessarily the case the other way around.
- Developers know their plugins will still function on 7.x+n (target 7.x, n≥0, so 7.0 plugins work on 7.1), but not necessarily the other way around.
-SNAPSHOTmeans that the versioned API is still in progress- If the minor version is 0 (e.g. 8.0-SNAPSHOT), anything may break before it is released and plugins cannot expect stability.
- If the minor version is greater than zero (e.g. 7.2-SNAPSHOT), anything up to the previous minor revision is still guaranteed (in this case, 7.1), but anything added since (in this case, for what will be 7.2) may still break, so cannot expect stability on unreleased features.
For the impl:
- A version string with an RC identifier means "recommended build", builds we consider as a reasonable quality that we would want to run ourselves.
- We tend to bump the build to indicate bug fixes and performance improvements, or any significant changes in the config or other systems that aren't related to the API (in this sense, the "patch" part of the version string isn't really a "patch" part and so it kind of moves away from the sem-ver ideology).
- For the 7.x.y part, 7.x is the version of the API that we guarantee for plugins, y is the recommended build version for this API series.
- Plugins written for 7.0 to 7.x will work. 7.x+n (n≥1) (including any SNAPSHOT features) may not work.
- Any server software that has the version
n.0.0-SNAPSHOTwhere the minor and recommended build numbers are 0 (or would the recommended build release be 1, I'd have to check) and the SNAPSHOT monkier is applied, versions are bleeding builds for testing the next version of the API only and may break at any time as we refine everything about it.
There was a problem hiding this comment.
Thank you for the comment and feedback! This in-depth explanation provides an outline I can follow to get it right this time. I figured a re-write was needed; I just wasn't sure yet how to proceed. Your feedback will save me much time. Thanks again!
There was a problem hiding this comment.
To be honest, what you had wasn't bad, it just seemed to kind of meander a bit much. You were doing a good job of being descriptive, just in the wrong areas! Regardless, I know that large comments that suggest a rewrite can be hard to take, so thank you for taking it in the good faith you have! :)
|
I have updated the PR to address most of the reviews provided. Thanks to all for the feedback and pointing out mistakes and better ways of writing the documentation. I did not work with versioning.rst. I had planned on spending much more time with it, and I have run out of time today. So, I am pushing the other changes I have made and will continue with the versioning.rst file Saturday. @ImMorpheus Thank you for the comment and feedback. The link is near the top. But like @dualspiral pointed out, the deluge of information drowns it out. Also, I made the corrections to I will be away from my computer tomorrow, so I won't be able to make any updates until Saturday. I should be able to look over the feedback about versioning.rst some tomorrow though. I will push those changes Saturday evening if possible. |
dualspiral
left a comment
dualspiral
left a comment
There was a problem hiding this comment.
I'm not convinced about splitting into versions and filenames, as the filename for our impls is pretty much the version. I would perhaps split it into API and Implementation versions and rejig stuff so server owners and plugin developers have targetted pages. It doesn't invalidate anything that's happened here as most of what is written may just need a cut and paste job into different homes.
So, something like this:
|--> SpongeAPI Versioning & Filenames
Versioning (inc. common stuff) ---|--> Legacy SF/V Versioning
|--> SpongeForge/Vanilla Versioning & Filenames
I would hold off on doing this until that's discussed though - this isn't a request for change but a request for input to try to ensure that duplication is minimised and that people can minimise the pages they look at (the quick start guide for setting up a server came about because we had a lot of pages for how to set up a server, but no "reference page").
It would be instructive, should there be any confusion, to read SpongePowered/SpongeForge#2367 where the version changes were proposed which might give clarity.
Else, I have a few comments below.
source/versions/filenames.rst
Outdated
| .. note:: | ||
|
|
||
| The first format without the build information is the release and recommended build format. The second format with | ||
| build information is the *SNAPSHOT* format. This version is still in development. |
There was a problem hiding this comment.
Maybe mention that this format is only used as raw downloads. Depending on the API via Gradle or Maven will download a formatted named jar as the recommended build format (spongeapi-7.2.0-SNAPSHOT.jar). Downloading via browser for specific builds will result in the timestamped jar file.
There was a problem hiding this comment.
spongeapi-7.2.0-SNAPSHOT.jar is the recommended build format? I thought the -SNAPSHOT label means it is still in development.
There was a problem hiding this comment.
Added another format. May need to change further to have the appropriate label.
|
I rewrote versioning.rst and corrected/improved filenames.rst.
@dualspiral I get what you are saying, and I agree, although I had already made some changes along these lines. I left the changes I had made to see if they suffice and to allow input from others. It wouldn't take much time to make the changes, so we can go that route if decided. I think your solution might be better since I am concerned that readers will brush over the warning and read/use the balance of the page anyways. Also, I have read #2367 quite a bit; actually, I have printed sections of it and highlighted parts throughout the pages. I am concerned this may be tripping me up though. I read all comments and try to implement them with the explanations in that issue as backdrops. My concern is that some of the information may have changed, but I keep stumbling because I am not aware of those changes. I don't want to come across as not listening or being hard headed. I'm just trying to use feedback in light of the explanations in the issue. @gabizou Please check comments concerning the SpongeAPI filename format. Thank you all for the comments and feedback! |
|
Added two more commits:
|
|
@ImMorpheus - your review is the last hurdle. If you're happy with the changes we can publish this. |
Signed-off-by: Grauldon <17791090+Grauldon@users.noreply.github.com>
Signed-off-by: Grauldon <17791090+Grauldon@users.noreply.github.com>
Signed-off-by: Grauldon <17791090+Grauldon@users.noreply.github.com>
Signed-off-by: Grauldon <17791090+Grauldon@users.noreply.github.com>
|
|
||
| ``spongeforge-<MCVersion>-<ForgeBuild>-<APIMajor>.<LatestAPIMinorRelease>.<RecommendedVersion(-RC<BuildNumber>)>.jar`` | ||
|
|
||
| +----------------------+-----------------------------------------------------------------------------------------------+ |
There was a problem hiding this comment.
I'm not sure, but the tables without headers look a little bit strange. Should we add the headers?
ST-DDT
left a comment
ST-DDT
left a comment
There was a problem hiding this comment.
I'm unsure about the missing table headers, but otherwise it looks good to me.
Preview updated.
dualspiral
left a comment
dualspiral
left a comment
There was a problem hiding this comment.
I'll add my review! :)
I think this is good to go. We can fix minor quibbles later as they come up, no point batting this around further.
|
should versioning be a main category? if it should it should be moved down in the sidebar |
Yes, unless you have a good idea where to place it otherwise.
I somewhat agree with that. Any suggestion for the target ordering? |
|
probably like this, so after creating a server and before dev work as kinda a bridge the ordering and naming kinda needs a general makeover anyway but thats out of scope for this pr |
|
I like phit's suggestion on the sidebar. I can also add the table headers while making that update, perhaps I also realized I forgot a parenthetical note on
to
It will look just like the parenthetical notes in Any thoughts on table headers and the note or further comments about phit's suggestion? |
|
Those headless tables seem OK by me, they are just another way of doing a list. |
Signed-off-by: Grauldon <17791090+Grauldon@users.noreply.github.com>
8 participants
This PR addresses SpongeDocs #768 and SpongeForge Issue #2367.
It changes SpongeDocs by creating a new directory for the topic and adding pages explaining how Sponge manages versions. It also updates existing files to move version topics to one place within the SpongeDocs contents and adds references from existing locations to the new pages. The home page is also updated to reference the new pages.
The first commit updates SpongeDocs to provide the current Java version update shipped with the Mojang installer (1.8.0_74). This information is on the Minecraft Wiki for the Windows versions; I downloaded the Mac OS X version and confirmed 1.8.0_74 is inside the .dmg file.