Create first AsciiDoc setup to generate the documentation for openMDM
Change-Id: I0937c590bc5845635cfdfe13cc30978bfe527045
Signed-off-by: Simon Skoczylas <simon.skoczylas@karakun.com>
diff --git a/doc/build.gradle b/doc/build.gradle
new file mode 100644
index 0000000..d4bfc1b
--- /dev/null
+++ b/doc/build.gradle
@@ -0,0 +1,40 @@
+buildscript {
+ repositories {
+ jcenter()
+ }
+}
+
+plugins {
+ id 'org.asciidoctor.jvm.convert' version '3.1.0'
+ id 'org.asciidoctor.jvm.pdf' version '3.1.0'
+}
+
+repositories {
+ jcenter()
+}
+
+asciidoctor {
+ options doctype: 'book'
+ attributes toclevels: 4, toc: 'left', sectnums: 'numbered'
+ sourceDir file('src')
+ sources {
+ include 'index.adoc'
+ }
+ outputDir file('build/docs')
+ baseDirFollowsSourceDir()
+}
+
+asciidoctorPdf {
+ options doctype: 'book'
+ attributes toclevels: 4, toc: 'auto', sectnums: 'numbered'
+ sourceDir file('src')
+ sources {
+ include 'index.adoc'
+ }
+ outputDir file('build/pdf')
+ baseDirFollowsSourceDir()
+}
+
+
+build.dependsOn(asciidoctorPdf)
+build.dependsOn(asciidoctor)
\ No newline at end of file
diff --git a/doc/src/index.adoc b/doc/src/index.adoc
new file mode 100644
index 0000000..df399b2
--- /dev/null
+++ b/doc/src/index.adoc
@@ -0,0 +1,8 @@
+= Installation and Setup Guide for the openMDM(R) Application
+Eclipse mdmbl project
+
+:toc:
+
+include::releases.adoc[]
+
+include::introduction.adoc[]
\ No newline at end of file
diff --git a/doc/src/introduction.adoc b/doc/src/introduction.adoc
new file mode 100644
index 0000000..937a425
--- /dev/null
+++ b/doc/src/introduction.adoc
@@ -0,0 +1,121 @@
+== Introduction
+
+=== General
+
+This document serves as a setup and installation guide for the Eclipse mdmbl project. +
+For **developers** is describes how to setup the environment, where the source code of the project can be found, retrieved,build and deployed.
+
+For **users** interested only in deploying / installing the openMDM Application, start here.
+
+**Note**: This guide describes the deployment on a local machine only,
+for installing the application in a company infrastructure, please contact your administrators to support you with firewalls and proxy configurations, grant permissions, etc.
+
+**Mailinglists**:
+
+* For development communication we use the mdmbl mailing list: +
+https://dev.eclipse.org/mailman/listinfo/mdmbl-dev
+* The openMDM Working group mailing list: +
+https://dev.eclipse.org/mailman/listinfo/open-measured-data-wg
+
+**For contributing to the mdmbl project you need to sign the ECA** +
+(Eclipse Contributor Agreement): https://wiki.eclipse.org/ECA
+
+
+**Helpful Links:**
+
+* Eclipse Wiki - openMDM EWG: +
+https://wiki.eclipse.org/Open-Measured-Data-Management-WG
+* Eclipse Project openMDM@BL: +
+https://projects.eclipse.org/projects/technology.mdmbl
+* Eclipse Bugzilla mdmbl issues: +
+https://bugs.eclipse.org/bugs/buglist.cgi?quicksearch=openmdm&list_id=16180271
+* openMDM git repos: +
+link:https://git.eclipse.org/c/?q=mdm[https://git.eclipse.org/c/?q=mdm]
+
+**Downloads:**
+Get the artefacts from the Project Download Page: openMDM_application-<version>.zip +
+https://projects.eclipse.org/projects/technology.mdmbl/downloads
+
+=== Requirements and Bugs
+
+**Requirements:**
+
+* Requirements are created in the Eclipse Bugzilla System [1]
+* Requirements are ordered by priority and maturity by the Steering Committee
+* for every REQU issue one or more Eclipse Bugzilla Tasks are created
+* mdmbl dev team works on the Bugzilla issues [1] +
+https://bugs.eclipse.org/bugs/buglist.cgi?quicksearch=mdmbl
+
+**Bugzilla issues:**
+
+* Requirements
+* “real” bugs from internal or external
+* technical requirements / enhancements from the team
+
+=== Use of new Frameworks / IP Management
+
+To introduce a new framework to the code the QA guidelines of the EWG and the Legal Process of Eclipse (
+https://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf[https://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf]
+) has to be followed:
+
+* Get the approval for use from the the Architecture Committee. The members of the AC are listed here: +
+https://wiki.eclipse.org/Open-Measured-Data-Management-WG.
+* Get the IP approval from the Eclipse Foundation, see: +
+https://wiki.eclipse.org/images/5/50/OpenMDM_IP_management_and_Software_Licensing.pdf[OpenMDM_IP_management_and_Software_Licensing.pdf]
+
+Only if you have both approvals, you can use the libraries in the code!
+
+=== Branching and versioning
+
+There are releases and milestones for the code in org.eclipse.mdm, milestones are marked with “M”, e.g. 5.2.0M2 is the 2nd milestone on the way to the 5.2.0 release.
+
+Stable versions are on the **master** branch. +
+The current development happens on the **dev** branch. +
+There are also several other branches, please contact us via the mailing list if you need more information.
+
+The latest stable version is on the current master. Older stable versions are tagged with the version number, e.g. 5.1.0, 5.2.0M1.
+
+For all stable versions the build artefacts and documentation are made available on the mdmbl download page: +
+https://projects.eclipse.org/projects/technology.mdmbl/downloads
+
+Documentation and release notes in Git: +
+https://git.eclipse.org/c/mdmbl/org.eclipse.mdm.git/tree/
+
+=== Eclipse Infrastructure
+
+==== Gerrit
+
+The mdmbl project is using Gerrit for code reviews. To configure, refer to chapter
+https://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf[Configure Gerrit].
+
+Gerrit has a two stage reviewing system:
+
+1. when code is checked into Gerrit, a build is automatically started. Ther Gerrit flag “verified” is set to +1, if the build succeeded
+2. a committer has to review the code and if ok, the code review flag is set to +2
+
+
+==== Jenkins
+
+https://ci.eclipse.org/mdmbl/
+
+There a nightly builds for the dev and the master branches of org.eclipse.mdm +
+There are also builds for Gerrit and Sonar.
+
+==== Sonar
+
+Note: 5.2.0M2 - not working, build scripts under construction +
+The Eclipse SonarQube server is available via
+https://sonar.eclipse.org[https://sonar.eclipse.org/]. +
+Rules: Qualitygate - sonar way with findbugs
+
+Static code analysis is configured for the dev branch of org.eclipse.mdm +
+Generated and test sources are excluded.
+
+=== ODS Server used for Developer Tests
+
+All released versions are tested with the following ODS Server:
+
+* HiQSoft GmbH +
+https://www.highqsoft.com/de/avalon-asam-ods-server/
+* Peak Solution GmbH +
+http://www.peak-solution.de/de/produkte-leistungen/versuchs-messdatenmanagement/softwareloesungen/peak-ods-server/
\ No newline at end of file
diff --git a/doc/src/releases.adoc b/doc/src/releases.adoc
new file mode 100644
index 0000000..f449e80
--- /dev/null
+++ b/doc/src/releases.adoc
@@ -0,0 +1,46 @@
+== Milestones & Releases: New and Noteworthy
+
+=== Milestone 5.2.0M2
+
+The old repositories are not used any more, they will be archived soon. Do not use!
+
+**New Repository Structure**
+
+All code from the repositories
+
+* org.eclipse.mdm.api.base
+* org.eclipse.mdm.api.default
+* org.eclipse.mdm.api.odsadapter
+* org.eclipse.mdm.nucleus
+
+moved to **org.eclipse.mdm**, including the history, the branches master, dev release_candidate and existing committer feature branches. The following tags were created: 5.0.0, 5.1.0, 5.2.0M1. If you need an older tag file a Bugzilla Bug.
+
+The structure in the new repository:
+
+* root: build scripts, documentation and legal documentation
+* api/
+** base/: code from former repos org.eclipse.api.base and org.eclipse.api.default, package names are unchanged
+** odsadapter/: code from repo org.eclipse.api.odsadapter
+** atfxadapter/: code from repo org.eclipse.mdm.nucleus/org.eclipse.mdm.api.atfxadapter
+* nucleus/
+** code from repo org.eclipse.mdm.nucleus except for the atfxadapter component
+* gradle/: the gradle wrapper
+* doc/: documentation from org.eclipse.mdm.nucleus/doc
+* tools/: new folder for common tooling, e.g. formatter, repository migration file
+
+**New build parameter for headless build and deployment:** +
+see 6.6. Headless Deployment
+
+
+=== Milestone 5.2.0M1
+
+**Changes to MDMRealm:**
+
+Up to version 5.1.0 all Users had to be assigned the group `MDM` to use openMDM. +
+Since 5.2.0M1 users need one of the following groups: `Admin`, `DescriptiveDataAuthor`, `Guest`. +
+See `org.eclipse.mdm/readme.md#Configure LoginModule` for more information.
+
+**Database schema change for User Preference Service:**
+
+In this release openMDM 5 database schema was extended. +
+If you have an existing installation make sure to apply the provided update script to your database.
\ No newline at end of file
diff --git a/settings.gradle b/settings.gradle
index 72e2b44..62f05a3 100644
--- a/settings.gradle
+++ b/settings.gradle
@@ -30,3 +30,5 @@
include 'nucleus:freetextindexer'
include 'nucleus:preferences'
include 'nucleus:webclient'
+
+include 'doc'
\ No newline at end of file
