Restructuring the documentation

docs/adr/0020-TOSCA-definitions-contain-extactly-one-element.md

@@ -0,0 +1,30 @@
+# TOSCA Definitions contain excaly one element
+
+## Context and Problem Statement
+
+How should TOSCA data be stored?
+
+## Considered Options
+
+* Allow exactly one TOSCA Definitions child in a definition
+* Allow multiple TOSCA Definitions children in a definition
+
+## Decision Outcome
+
+Chosen option: "Allow exactly one TOSCA Definitions child in a definition", because
+- Definitions are not modeled as explicit element. Only the nested elements are handled by Winery.
+- That means, it is not possible to specify custom definitions bundling a customized subset of available elements.
+
+## License
+
+Copyright (c) 2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0

docs/dev/Encoding.md

@@ -5,7 +5,7 @@
 ## Example to understand double encoding of URIs in Winery
 
 In file systems, characters `/` and `:` are not allowed [source](https://stackoverflow.com/a/31976060/873282).
-The [design decision](../adr/0002-filesystem-folder-structure-using-type-namespace-id-structure) is that all files (node types, imports in CSARs, ...) are stored and structured using directories with human readable names.
+The [design decision](../adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md) is that all files (node types, imports in CSARs, ...) are stored and structured using directories with human readable names.
 Therefore, the namespace URI must be used in a encoded form, otherwise the name would not be valid (`http://www...`). 
 An example for such a directory name is `http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema`.
 Since (1) namespaces are URIs and (2) [percent-encoded](https://tools.ietf.org/html/rfc3986#section-2.1) URIs form valid directory names, URL encoding is used.

docs/dev/REST.md

@@ -0,0 +1,87 @@
+# REST
+
+All resources are implemented in classes in the package `org.eclipse.winery.repository.rest.resources`.
+We call all elements directly nested in the definitions element "components".
+They are implemented using JAX RS 1.1 using [Jersey 1.x](https://jersey.github.io/documentation/1.19.1/index.html).
+
+The full set the API is used by the Type, Template, and Artifact Management UI (see [User Documentation](../user/)).
+A subset of the API is used at [IWineryRepository](#iwineryrepository).
+
+## URL Structure
+
+The idea behind the URL structure may shortly describes by `ROOT/<componenttype>s/<double-encoded-namespace>/<double-encoded-id>/<resource-specific-part>`, which makes the structure similar to one of the [file system](RepositoryLayout).
+Encoding is done following [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.1). 
+An online URL-encoder may be found at: <http://www.albinoresearch.com/misc/urlencode.php>.
+
+For instance, the NodeType "NT1" in the namespace `http://www.example.com/NodeTypes` is found at the URL `nodetypes/http%253A%252F%252Fexample.com%252FNodeTypes/NT1/`.
+As the browser decodes the URL, the namespace and the id are double encoded. 
+Note the additional encoding of the symbol `%` in comparison to the encoding at the filesystem.
+This is due to security decisions to disallow `%2F` in URLs.
+
+The part until `<componenttype>s` is realized by ["AbstractComponentsResource" and its subclasses](#collections-of-components).
+The resource specific part is realized by [subclasses of AbstractComponentInstanceResource](#component-instances).
+
+More information on encoding is given at [Encoding](Encoding).
+
+## Collections of Components
+
+![AbstractCompoenentResource Inheritance](graphics/InheritanceOfAbstractComponentResource.png)  
+**Figure 6: Inheritance of AbstractComponentResource**
+
+Figure 6 shows the inheritance of AbstractComponentsResource. It contains an intermediate class
+"AbstractComponentsWithTypeReferenceResource" which handles a POST with an additional type. It is used at
+all components which have a type associated. These are artifact templates, node type implementations,
+relationship type implementations and policy templates.
+
+All logic is implemented in AbstractComponentsRessource.
+It handles creation of resources (using POST) and creation of AbstractComponentInstanceResources.
+
+## Component Instances
+
+![AbstractComponentInstanceResource Inheritance](graphics/InheritanceOfAbstractComponentInstanceResource.png)  
+**Figure 7: Inheritance of AbstractComponentInstanceResource**
+
+Figure 7 shows the inheritance of AbstractComponentInstanceResource.
+For each component, a class exists.
+Using Intermediate classes, common properties are handled.
+These are explained in the following sections.
+
+### AbstractComponentInstanceResourceWithNameDerivedFromAbstractFinal
+
+Several component instances have the attributes "name", "dervidedFrom", "abstract", and "final". These are
+handled in the class "AbstractComponentInstanceResourceWithNameDerivedFromAbstractFinal". In this group,
+type implementations, namely node type implementations and relationship type implementations can be found.
+
+Furthermore, type resources exist. These are grouped by the "EntityTypeResource". Within the context of this class,
+"TopologyGraphElementEntityTypeResource" is introduced. This class groups together "NodeTypeResource" and "RelationshipTypeResource".
+
+### AbstractComponentInstanceWithReferencesResource
+
+This class groups together classes with file references. Artifact Templates may reference files and a Service
+Template may reference plans. The user can copy files manually to the right place in the directory structure of
+the repository. By calling the method "synchronizeReferences()", the referenced stores in the XML are
+synchronized with the actually existing files. This is done whenever the XML is retrieved from the repository.
+
+#### GenericImportResource
+
+This class is used to handle different import types. Currently only CSD is supported. The class is
+"XSDImportResource".
+
+#### PolicyTemplateResource
+
+This class implements the resource for a policy template. Since a policy template does not contain any external
+file references, it is not modeled as child of "AbstractComponentInstanceWithReferencesResource".
+
+## License
+
+Copyright (c) 2013-2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0

docs/dev/ToolChain-initialization.md

@@ -0,0 +1,50 @@
+# Eclipse Winery Toolchain
+
+To contribute to Eclipse Winery development you need a GitHub account and access to <https://github.com/opentosca/winery>.
+Email your supervisor your GitHub username.
+
+- In case you did not choose an account name, use `flastname` as pattern:
+  `f` is the lower-case first letter of your firstname and
+  `lastname` is the lower-case lastname.
+- Due to open source development, your email adress will get public.
+  In case, you don't have a public email adress, we recommend to create one or use your student email adress.
+  In case you want to create a longer-lasting one, please use the GitHub username.
+  Example: `flastname@gmail.com`.
+- Please enable the git-hooks by executing `git config core.hooksPath .git-hooks` in the root of the repository.
+
+## Steps to get write access to the code repositories
+
+1. Email your supervisor your GitHub username and your development email address.
+2. Your supervisor adds you to the team "developers" at <https://github.com/opentosca> and <https://github.com/winery>.
+3. You will receive two emails from GitHub asking for your confirmation.
+4. Open the link <https://github.com/orgs/winery/invitation>.
+5. Open the link <https://github.com/orgs/OpenTOSCA/invitation>.
+
+## Steps to initialize the code repository
+
+  1. Clone <https://github.com/opentosca/winery> (it automatically becomes the `origin`).
+     - We recommend that git repositories reside in `c:\git-repositories`.
+     - Use [ConEmu](https://conemu.github.io/) as program for all your shells: `choco install conemu`.
+       Install [chocolatey](https://chocolatey.org/) to use the `choco` command.
+     - Execute `git clone https://github.com/OpenTOSCA/winery.git` in `c:\git-repositories`.
+  2. Change into the newly created directory `winery`: `cd winery`.
+  3. Add `upstream` as second remote: `git remote add upstream https://github.com/eclipse/winery.git`
+  4. Fetch everything from `upstream`: `git fetch upstream`
+
+## Steps to initialize the TOSCA repository
+
+Please go to the [quick start guide](../user/quickstart.md).
+
+## License
+
+Copyright (c) 2013-2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0

docs/dev/ToolChain.md

@@ -2,56 +2,20 @@
 
 <!-- toc -->
 
-- [GitHub - Start](#github---start)
-  * [Steps to get write access to the repositories](#steps-to-get-write-access-to-the-repositories)
-  * [Steps to initialize the repository](#steps-to-initialize-the-repository)
-  * [Steps for working on a topic](#steps-for-working-on-a-topic)
+- [Steps for working on a topic](#steps-for-working-on-a-topic)
 - [GitHub - Prepare Final Pull Request](#github---prepare-final-pull-request)
 - [GitHub - Create Final Pull Request](#github---create-final-pull-request)
 - [GitHub - Change Final Pull Request](#github---change-final-pull-request)
 - [GitHub - After Pull Request Got Merged](#github---after-pull-request-got-merged)
 - [Excursus: Git](#excursus-git)
-- [License](#license)
 
 <!-- tocstop -->
 
 This presents the tool chain used for creating and updating a pull request on GitHub.
 
-For setup the IDE, please go to the [DevGuide](./).
+For the general setup, please go to [ToolChain-initialization](ToolChain-initialization.md).
 
-## GitHub - Start
-
-To contribute to Eclipse Winery development you need a GitHub account and access to <https://github.com/opentosca/winery>.
-Email your supervisor your GitHub username.
-
-- In case you did not choose an account name, use `flastname` as pattern:
-  `f` is the lower-case first letter of your firstname and
-  `lastname` is the lower-case lastname.
-- Due to open source development, your email adress will get public.
-  In case, you don't have a public email adress, we recommend to create one or use your student email adress.
-  In case you want to create a longer-lasting one, please use the GitHub username.
-  Example: `flastname@gmail.com`.
-
-### Steps to get write access to the repositories
-
-1. Email your supervisor your GitHub username and your development email address.
-2. Your supervisor adds you to the team "developers" at <https://github.com/opentosca> and <https://github.com/winery>.
-3. You will receive two emails from GitHub asking for your confirmation.
-4. Open the link <https://github.com/orgs/winery/invitation>.
-5. Open the link <https://github.com/orgs/OpenTOSCA/invitation>.
-
-### Steps to initialize the repository
-
-  1. Clone <https://github.com/opentosca/winery> (it automatically becomes the `origin`).
-     - We recommend that git repositories reside in `c:\git-repositories`.
-     - Use [ConEmu](https://conemu.github.io/) as program for all your shells: `choco install conemu`.
-       Install [chocolatey](https://chocolatey.org/) to use the `choco` command.
-     - Execute `git clone https://github.com/OpenTOSCA/winery.git` in `c:\git-repositories`.
-  2. Change into the newly created directory `winery`: `cd winery`.
-  3. Add `upstream` as second remote: `git remote add upstream https://github.com/eclipse/winery.git`
-  4. Fetch everything from `upstream`: `git fetch upstream`
-
-### Steps for working on a topic
+## Steps for working on a topic
 
   1. Create a new branch for each topic (fix a bug, add functionality) and name it accordingly.
      - Thesis: `thesis/SHORT-THESIS-TITLE`. Replace `SHORT-THESIS-TITLE` with something meaningful

docs/dev/angular-ui.md

@@ -1,6 +1,6 @@
 # Eclipse Winery Angular Apps
 
-tODO: generisch für beide apps
+TODO: generisch für beide apps
 
 ## Prerequisites
 1. Install [git](https://git-scm.com)

docs/dev/branches.md

@@ -0,0 +1,53 @@
+# Branches
+
+The `master` branch is always compiling and all tests should go through.
+It contains the most recent improvements.
+All other branches are real development branches and might event not compile.
+
+There are no explicit branches for stable versions as winery is currently in development-only mode.
+
+We try to follow following naming conventions:
+
+  - Bugfix: `fix/issue-NNN` or `fix/SHORT-TITLE` if fixing an issue with a number or give it a title
+  - Feature: `feature/issue-NNN` or `feature/SHORT-TITLE`
+  - WIP: `wip/SHORT-TITLE` for work in progress without issue and you know won't be finished soon
+  - Thesis: `thesis/SHORT-THESIS-TITLE`. Replace `SHORT-THESIS-TITLE` with something meaningful
+  - EnPro: prefix `fix`, `feature`, `wip` (see below) with `enpro/`
+  - StuPro: prefix `fix`, `feature`, `wip` (see below) with `stupro/`
+
+See <https://gist.github.com/revett/88ee5abf5a9a097b4c88> for a discussion and other ideas.
+
+## Editing the gh-pages branch of the test repository
+
+It is beneficial to have the [gh-pages branch](https://github.com/winery/test-repository/tree/gh-pages) of the test repository checked out in a second directory to be able to work in Winery and on the homepage in parallel.
+Git supports that by the [worktree command](https://git-scm.com/docs/git-worktree):
+
+1. Change directory to `C:\winery-repository`
+2. Execute `git worktree add ..\git-repositories\winery-repository-gh-pages gh-pages` to check out the `gh-pages` branch into `C:\git-repositories\winery-repository-gh-pages`.
+
+Full output:
+
+```
+$ C:\winery-repository
+> git worktree add ..\git-repositories\winery-repository-gh-pages gh-pages
+Preparing ../git-repositories/winery/winery-repository-gh-pages (identifier winery-repository-gh-pages)
+HEAD is now at 5017713 Initial documentation
+```
+
+## License
+
+Copyright (c) 2013-2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+
+ [Apache Maven]: https://maven.apache.org/
+ [bower]: https://bower.io/
+ [jsPlumb#165]: https://github.com/jsplumb/jsPlumb/issues/165

docs/dev/building.md

@@ -0,0 +1,39 @@
+# Building Winery
+
+Winery uses [Apache Maven] for Java depedency management.
+[bower] is used for fetching JavaScript dependencies.
+Bower is installed automatically using the [frontend-maven-plugin].
+We recommend installing JDK8 by using `choco install jdk8` to be able to update it via `choco upgrade all`. See at the homepage of [chocolatey] for more information.
+Please follow the the next step "Making the wars" before importing the project into an IDE.
+
+### Making the wars
+
+Run `mvn package`.
+In case [bower] fails, try to investigate using `mvn package -X`.
+You can start bower manually in `org.eclipse.winery.repository` and `org.eclipse.winery.topologymodeler` by issuing `bower install`.
+
+There are four WARs generated:
+
+* `org.eclipse.winery.repository.rest/target/winery.war` - the REST interface to the repository
+* `org.eclipse.winery.repository.ui/target/winery-ui.war` - the UI for the repository
+* `org.eclipse.winery.topologymodeler/target/winery-topologymodeler.war` - the topology modeler
+* `org.eclipse.winery.workflowmodeler/target/winery-workflowmodeler.war` - the workflow modeler
+
+They can be deployed on a Apache Tomcat runtime environment.
+
+ [Apache Maven]: https://maven.apache.org/
+ [bower]: https://bower.io/
+
+## License
+
+Copyright (c) 2013-2018 Contributors to the Eclipse Foundation
+
+See the NOTICE file(s) distributed with this work for additional
+information regarding copyright ownership.
+
+This program and the accompanying materials are made available under the
+terms of the Eclipse Public License 2.0 which is available at
+http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0
+which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+SPDX-License-Identifier: EPL-2.0 OR Apache-2.0