Add guidance on appropriate choice of version number for new plugins (#…

…750)

* Add guidance on appropriate choice of version number for new plugins

Fixes #727

* Be bold instead of a headline

* Use API version instead of Minecraft version

* Fix comments

source/plugin/project/gradle.rst

@@ -40,7 +40,8 @@ These few lines handle most settings you would normally do manually:
 * Set your project to compile with Java 8
 * Add Sponge's Maven repository (and Maven Central)
 * Set up a plugin with the project name in lower case as **plugin ID**
-* Automatically includes the project name, description and version in :doc:`/plugin/plugin-meta`.
+* Automatically includes the project name, description and :doc:`version <../project/version-numbers>` in
+  :doc:`/plugin/plugin-meta`.
 
 Manually setting the plugin ID
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/plugin/project/index.rst

@@ -35,3 +35,4 @@ Setting Up Your Project
 
     gradle
     maven
+    version-numbers

source/plugin/project/maven.rst

@@ -42,7 +42,7 @@ groupId         io.github.user             The maven groupId, useful more for pl
                                            more or less match your package name
 artifactId      myproject                  The project id, also used as plugin id and name of the generated folder
 version         1.0-SNAPSHOT               The initial version for your plugin. Can (and should) be changed as
-                                           development progresses
+                                           development progresses. See :doc:`../project/version-numbers` for details.
 package         io.github.user.myproject   The package your plugin class will be generated in
 githubProject   user/repo                  The GitHub project. If a value is specified that is not user/repo, issue
                                            tracking and SCM sections are added to the pom

source/plugin/project/version-numbers.rst

@@ -0,0 +1,83 @@
+Version Numbers
+===============
+
+Your plugin needs a unique version number in order to allow humans to find out which version of a plugin is the
+successor of the other. There are plenty of versioning schemes that you could use for your own plugin. In the following
+part we explain a few concepts with their pros and cons.
+
+Sponge recommends to use a version identifier that consists of either two or three numeric version parts separated with
+a ``.`` and additional label appended with a hyphens ``-`` such as ``3.1`` or ``1.0.3-API7`` similar to SemVer.
+Start with ``1.x`` if your plugin is ready. Start with ``0.x`` if your plugin is not yet ready or unstable.
+
+.. note::
+
+    While Sponge recommends using the above versioning scheme, plugin authors are free to choose their own. Please keep
+    in mind that your users have to deal with a multitude of versioning schemes, so keep it simple.
+
+SemVer
+------
+
+`SemVer <https://semver.org/>`_ is a commonly used semantic versioning scheme. It consists of three numeric blocks that
+are separated by dots and additional labels which are appended using hyphens. The three numeric blocks make up
+the ``MAJOR``, ``MINOR`` and ``PATCH`` version parts. 
+
+* A change in the **MAJOR** version indicates that you made incompatible API changes. Rewriting large parts of your
+  plugin or the entire plugin would also count as incompatible changes.
+* A change in **MINOR** version indicates that a feature has been added without breaking backwards
+  compatibility.
+* A change in the **PATCH** version indicates that some bugs have been fixed.
+
+The labels can be used to mark builds as pre-releases or contain build metadata such as the supported minecraft version.
+If you increase one part of the version, then you will set the following parts back to zero. Using this strategy you
+can find the latest version by comparing the version blocks with each other, however this scheme does not contain any
+information about the release order for versions which differ in two version number blocks. Example: Version ``1.0.9``
+would be released after ``1.0.8``, but version ``1.1.0`` could be released before, after or even at the same time as
+either of them. 
+
+.. note::
+
+    The SpongeAPI uses this versioning scheme.
+
+**Examples**
+
+* ``0.1.0``
+* ``1.0.0``
+* ``1.1.0-SNAPHOT``
+* ``3.12.21-API7``
+
+**Pros**
+
+* Easy to read and understand
+
+**Cons**
+
+* Mostly API oriented so the terms don't really apply if you don't provide an API in your plugin.
+
+Timestamp
+---------
+
+This is a less commonly used versioning scheme, but it is also a very simple one, as it does not contain any additional
+information in the version numbers. It does not matter which separators you use (if any) or which date and time parts
+you include. However we recommend you to order date and time parts in the descending order of duration like
+``YYYY-MM-DD``. If you sort your files alphabetically, please make sure that the order would be the same as the version
+order. It is also possible to add a build qualifier or a build number.
+
+**Examples**
+
+* ``18.01.31``
+* ``v2018-05-29.1``
+* ``2018.01.13-SNAPHOT``
+
+**Pros**
+
+* Easy to read and understand
+
+**Cons**
+
+* Does not contain any information about compatibility.
+
+Other
+-----
+
+You can read more about Software versioning and versioning schemes
+`online <https://en.wikipedia.org/wiki/Software_versioning>`_.

source/plugin/workspace/eclipse.rst

@@ -7,8 +7,8 @@ build system such as Maven or Gradle <../buildsystem/>`.
 
 .. note::
 
-    A tutorial by Mumfrey showing the setup of a Sponge workspace in Eclipse, using the new features in Buildship and ForgeGradle,
-    can be viewed `here <https://www.youtube.com/watch?v=R8NcakQtHVI>`_.
+    A tutorial by Mumfrey showing the setup of a Sponge workspace in Eclipse, using the new features in Buildship and
+    ForgeGradle, can be viewed `here <https://www.youtube.com/watch?v=R8NcakQtHVI>`_.
 
 Gradle
 ======
@@ -18,7 +18,8 @@ Preparing Gradle
 
 .. note::
 
-    Gradle is automatically included in Eclipse starting from the Neon release (June 22, 2016) and later. These steps are only required for earlier versions.
+    Gradle is automatically included in Eclipse starting from the Neon release (June 22, 2016) and later. These steps
+    are only required for earlier versions.
 
 You must first install the **Gradle Integration Plugin** before using Gradle in Eclipse. This only needs to be done
 upon the creation of your first project.
@@ -75,7 +76,7 @@ Creating your project
 
   * Your **Group ID** should usually correspond to your Java package name. See :doc:`../plugin-class` for details.
   * Your **Artifact ID** should usually correspond to your **plugin ID** you chose earlier, e.g. ``myplugin``.
-  * Your **Version** is up to you.
+  * Your **Version** is up to you. See :doc:`../project/version-numbers` for details.
 
 * Click ``Finish``.
 

source/plugin/workspace/idea.rst

@@ -3,7 +3,8 @@ Setting Up IntelliJ IDEA
 ========================
 
 This article describes how to configure your **IntelliJ IDEA** workspace for plugin development with SpongeAPI and
-:doc:`a build system such as Maven or Gradle <../buildsystem/>` or the `Minecraft Development plugin <https://minecraftdev.org/>`_.
+:doc:`a build system such as Maven or Gradle <../buildsystem/>` or the
+`Minecraft Development plugin <https://minecraftdev.org/>`_.
 
 If you want to create your project completely from scratch, please skip ahead to the Gradle or Maven sections.  
 Using the Minecraft Dev plugin sets up a working starting point and eliminates some of the guesswork in getting
@@ -38,7 +39,7 @@ Creating Your Project from a Template
 
   * Your **Group ID** should usually correspond to your Java package name. See :doc:`../plugin-class` for details.
   * Your **Artifact ID** should usually correspond to your **plugin ID** you chose earlier, e.g. ``myplugin``.
-  * Your **Version** is up to you.
+  * Your **Version** is up to you. See :doc:`../project/version-numbers` for details.
 
 * Select your desired build tool, either Gradle or Maven, and click ``Next``.
 * Check your **Plugin Name** and **Main Class Name** to make sure they are what you want.
@@ -50,7 +51,7 @@ Creating Your Project from a Template
   is working when you run it.
 
 Editing the Project Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Refer to the Gradle_ or Maven_ configuration sections, depending on what you chose during project creation.
 
@@ -69,7 +70,7 @@ Creating a Plugin from Scratch -- Gradle
 
   * Your **Group ID** should usually correspond to your Java package name. See :doc:`../plugin-class` for details.
   * Your **Artifact ID** should usually correspond to your **plugin ID** you chose earlier, e.g. ``myplugin``.
-  * Your **Version** is up to you.
+  * Your **Version** is up to you. See :doc:`../project/version-numbers` for details.
 
 * Click ``Next`` twice, name your project, and click ``Finish``.
 * The project will be created without a ``src`` directory.  If you add java files to the incorrect
@@ -108,7 +109,7 @@ Creating Your Project
 
   * Your **Group ID** should usually correspond to your Java package name. See :doc:`../plugin-class` for details.
   * Your **Artifact ID** should usually correspond to your **plugin ID** you chose earlier, e.g. ``myplugin``.
-  * Your **Version** is up to you.
+  * Your **Version** is up to you. See :doc:`../project/version-numbers` for details.
 
 * Click ``Next``.
 * Enter your project's name, and click ``Finish``.
@@ -122,7 +123,7 @@ Editing the Project Configuration
 * Import the Maven changes, if prompted.
 
 Testing Your Plugin
-====================
+===================
 
 The following instructions are a quick way to test your plugin, but won't be the most efficient way
 to iteratively develop.