Updated documentation. Sphinx Gradle-plugin seems broken though.

Signed-off-by: Philip R. Kensche <p.kensche@dkfz-heidelberg.de>

GitPrivacy: eNL43MfR9zGBAfdW4YpC/MGfouMqQdRDn+NJC2pI7LaXUe7xefl0RZhrnujT7BoDn1VtB0zwLxQ= RzRXFFeqYMsM4NOMAomGW4mQnBCz5ynu0eL/ox20bhw1j8prCx6/Xn13BqlZoc6WFrR1ykMqLGc=

README.md

@@ -8,9 +8,14 @@ Roddy is a framework for development and management of workflows on a batch proc
 
 > No new features will be implemented for Roddy! We will continue to fix bugs occurring with currently existing workflows. On the long run, existing workflows should be migrated to other workflow management systems. 
 
+> NOTE: Roddy is for research-use only (RUO).
+
 # Documentation
 
-You can find the documentation at [Read the Docs](http://roddy-documentation.readthedocs.io), including [detailed installation instructions](https://roddy-documentation.readthedocs.io/en/latest/installationGuide.html).
+You can find the documentation at [Read the Docs](http://roddy-documentation.readthedocs.io), including 
+
+* [detailed installation instructions](https://roddy-documentation.readthedocs.io/en/latest/installationGuide.html)
+* [contributors documentation](https://roddy-documentation.readthedocs.io/en/stable/roddyDevelopment/developersGuide.html)
 
 # Workflows
 
@@ -31,3 +36,16 @@ The following plugins are available as support for the workflows:
   * [COWorkflowBasePlugin](https://github.com/DKFZ-ODCF/COWorkflowsBasePlugin) with basic control code for many of the workflows
   * [PluginBase](https://github.com/TheRoddyWMS/Roddy-Base-Plugin) just the plugin base-class from which other plugins are derived
   * [DefaultPlugin](https://github.com/TheRoddyWMS/Roddy-Default-Plugin) with the `wrapInScript.sh` that wraps all Roddy cluster jobs
+
+# Change Log
+
+The change log can be found [here](CHANGELIST.md).
+
+# Licence
+
+## License
+
+By contributing your code, you agree to license your contribution under the terms of the MIT License:
+
+http://opensource.org/licenses/mit-license.html
+https://www.github.com/TheRoddyWMS/Roddy/LICENSE.txt

build.gradle

@@ -25,7 +25,7 @@ plugins {
     id 'pmd'
     id 'org.cyclonedx.bom' version '1.8.2'
     id 'maven-publish'
-    id 'kr.motd.sphinx' version '2.10.0'         // Apache 2.0
+    id 'kr.motd.sphinx' version '2.10.1'         // Apache 2.0
     id 'application'
 }
 
@@ -38,7 +38,6 @@ group = "com.github.theroddywms"
  */
 ext.allowDirtyRepo = (project.hasProperty("allowDirty") && project.allowDirty == "true")
 
-// apply plugin: "java"
 apply plugin: 'distribution'
 apply plugin: 'groovy'
 apply plugin: 'kr.motd.sphinx'  // Apache 2.0
@@ -241,7 +240,6 @@ distributions {
             }
             from("./") {
                 include("LICENSE")
-                include("CONTRIBUTING.md")
                 include("CONTRIBUTORS.md")
                 include("3RDPARTY_LICENSES")
                 include("CHANGELIST.md")
@@ -259,7 +257,6 @@ distributions {
                 include("roddy.sh")
                 include("README.md")
                 include("LICENSE")
-                include("CONTRIBUTING.md")
                 include("CONTRIBUTORS.md")
                 include("3RDPARTY_LICENSES")
                 include("CHANGELIST.md")
@@ -309,11 +306,11 @@ task listConfigurations {
 }
 
 task allBoms() {
-    // a grouping task to execute the CycloneDxTask for each configuration
     group = "reporting"
+    description = "A grouping task to execute the CycloneDxTask for each configuration"
 }
 
-rootProject.configurations.each { configuration ->
+rootProject.configurations.each { Configuration configuration ->
     String name = configuration.name
     task "${name}Bom"(type: CycloneDxTask) {
         group = "reporting"

dist/bin/develop/buildinfo.txt

@@ -1,3 +1,3 @@
 JDKVersion=
-GroovyVersion=
+GroovyVersion=2.4
 RoddyAPIVersion=3.8

docs/installationGuide.rst

@@ -15,6 +15,7 @@ Installation guide
 
 There are several minor versions of Roddy, which can be downloaded and installed in the same directory.
 Minor versions mark changes in the Roddy API. Usually Roddy plugins are only compatible to a specific minor version.
+The full documentation of the how version numbers are used with roddy can be found in the :doc:`roddyDevelopment/developersGuide`.
 Installations for the different versions differ a bit, so we list all versions here.
 
 Premises

docs/roddyDevelopment/developersGuide.rst

@@ -33,16 +33,19 @@ We know, that we have a lot of issues in our codebase, but we listen to every im
 Development model
 ~~~~~~~~~~~~~~~~~
 
-For development we follow the standard `Github flow`_ with feature branches
+For development we mostly follow the standard `Github flow`_ with feature branches
 getting merged directly back into the master branch. Releasing in simply done
 by putting a tag on the master branch and let the continuous integration
-pipeline (Travis) deploy a release archive to Github releases
+pipeline (Travis) deploy a release archive to Github releases.
+
+This is extended by release branches in case bug-fixes need to be backported to older versions. Release branches names must match the regular expression ``ReleaseBranch_\d+\.\d+(\.\d+)?``.
+
 
 Settings for Groovy classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-We will not accept Groovy classes without the @CompileStatic annotation. If you are in the rare situation that you need dynamic dispatch on more than
-the object (this) itself, you can mark the affected methods with @CompileDynamic.
+We will not accept Groovy classes without the ``@CompileStatic`` annotation. If you are in the rare situation that you need dynamic dispatch on more than
+the object (this) itself, you can mark the affected methods with ``@CompileDynamic``.
 
 API documentation
 ~~~~~~~~~~~~~~~~~
@@ -54,25 +57,31 @@ Roddy versioning scheme
 
 We are using `semantic versioning`_.
 
-Roddy version numbers consist of three entries: $major.$minor.$build.
-The build number is also sometimes called patch number.
+Roddy version numbers consist of three numbers: ``$major.$minor.$build``.
+The ``$build`` number is also sometimes called patch number.
 
-The $major entry is used to mark API-breaking changes in the Roddy core
+The ``$major`` number is used to mark API-breaking changes in the Roddy core
 functions. Backward compatibility is not granted and Roddy
-will not execute plugins built with different $major versions.
+will not execute plugins built with different ``$major`` versions.
 
-The $minor entry marks smaller changes which extend the Roddy API.
+The ``$minor`` number marks additions and new features that extend the Roddy API, but do not break the existing API.
 Backward compatibility of Roddy to the plugin should not be affected, such
 that your old plugins should run with the newer Roddy version.
 
-The combination of $major.$minor can somehow be seen as the API level
+The ``$build`` number marks small changes that have no influence on the operation of Roddy, except that they may make Roddy work in situations in which terminated with an error before, e.g., in case of bugs.
+
+.. Note:: The repository contains old tags that end in ``-1``, ``b`` or ``b1``. These are old development tags that were used during the earlier development of Roddy.
+
+The combination of ``$major.$minor`` can be seen as the API level
 of Roddy. For a “full API level” the plugin versions of “PluginBase” and
 “DefaultPlugin” need to be considered as well.
 
+Roddy plugin versioning scheme
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Basically the same versioning convention applies to the plugins, but note
 that we advise authors to base the plugin versions not on the Roddy core
-versions, but only on the semantics of the analysis. The details have not
-yet been fully worked out, but basically this means,
+versions, but only on the semantics of the analysis. At least, if your plugin produces different results, and you want to express this to your users, bump the version number accordingly. For instance,
 
   * modified output files warrant a major level increase
   * added output files warrant a minor level increase