From eea26c2aeed01da9a8c22957ba95b748f6e302eb Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Wed, 29 Aug 2018 13:29:34 +0200 Subject: [PATCH] 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 | 3 +- source/plugin/project/index.rst | 1 + source/plugin/project/maven.rst | 2 +- source/plugin/project/version-numbers.rst | 83 +++++++++++++++++++++++ source/plugin/workspace/eclipse.rst | 9 +-- source/plugin/workspace/idea.rst | 13 ++-- 6 files changed, 99 insertions(+), 12 deletions(-) create mode 100644 source/plugin/project/version-numbers.rst diff --git a/source/plugin/project/gradle.rst b/source/plugin/project/gradle.rst index 5cde07a3c1e1..2b0d7368c581 100644 --- a/source/plugin/project/gradle.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/plugin/project/index.rst b/source/plugin/project/index.rst index 32b00f445ba0..3dbc8b536a5a 100644 --- a/source/plugin/project/index.rst +++ b/source/plugin/project/index.rst @@ -35,3 +35,4 @@ Setting Up Your Project gradle maven + version-numbers diff --git a/source/plugin/project/maven.rst b/source/plugin/project/maven.rst index 6f02e435417f..ac41b8198efa 100644 --- a/source/plugin/project/maven.rst +++ b/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 diff --git a/source/plugin/project/version-numbers.rst b/source/plugin/project/version-numbers.rst new file mode 100644 index 000000000000..e6a803e2b0b6 --- /dev/null +++ b/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 `_ 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 `_. diff --git a/source/plugin/workspace/eclipse.rst b/source/plugin/workspace/eclipse.rst index 64922f38cf14..2967ab8dfd44 100644 --- a/source/plugin/workspace/eclipse.rst +++ b/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 `_. + 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 `_. 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``. diff --git a/source/plugin/workspace/idea.rst b/source/plugin/workspace/idea.rst index 66a5efbbbcdc..e2479597bcd9 100644 --- a/source/plugin/workspace/idea.rst +++ b/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 `_. +:doc:`a build system such as Maven or Gradle <../buildsystem/>` or the +`Minecraft Development plugin `_. 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.