refactor(docs): restructure documentation directory and framework

CONTRIBUTING.md

@@ -1,12 +1,10 @@
-Contributing to the Project
-===================================
+# Contributing to the Project
 
 Thank you for your interest in contributing to
 the [Eclipse Dataspace Connector](https://projects.eclipse.org/projects/technology.dataspaceconnector)!
 
 ## Table of Contents
 
-* [Project Description](#project-description)
 * [Code Of Conduct](#code-of-conduct)
 * [Eclipse Contributor Agreement](#eclipse-contributor-agreement)
 * [How to Contribute](#how-to-contribute)
@@ -17,12 +15,9 @@ the [Eclipse Dataspace Connector](https://projects.eclipse.org/projects/technolo
 * [Project and Milestone Planning](#project-and-milestone-planning)
   * [Milestones](#milestones)
   * [Projects](#projects)
+  * [Releases](#releases)
 * [Contact Us](#contact-us)
 
-## Project Description
-
-See [README.md](README.md) for a comprehensive project description.
-
 ## Code Of Conduct
 
 See the [Eclipse Code Of Conduct](https://www.eclipse.org/org/documents/Community_Code_of_Conduct.php).
@@ -218,7 +213,19 @@ It can be unassigned or moved to any other project that is provided.
 In every project, an issue passes four stages: `Backlog`, `In progress`, `Review in progress`, and `Done`,
 independent of their association to a specific milestone.
 
-### Contact Us
+### Releases
+
+Please find more information about our release approach [here](docs/developer/releases.md).
+
+## Contact Us
 
 If you have questions or suggestions, do not hesitate to contact the project developers via
 the [project's "dev" list](https://dev.eclipse.org/mailman/listinfo/dataspaceconnector-dev). 
+
+You may also want to join our [Discord server](https://discord.gg/n4sD9qtjMQ).
+
+There, we provide a biweekly meeting on fridays 2-3 p.m. (CET) to give any interested person the
+opportunity to get in touch with the committer team. We are meeting in the "general" voice channel.
+Find more details about the schedule [on GitHub](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/discussions/1303).
+
+_If you have a "contributor" or "committer" status, you will also have access to private channels._

README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
   <a href="#contributing">Contribute</a> •
-  <a href="https://eclipse-dataspaceconnector.github.io/DataSpaceConnector/">Docs</a> •
+  <a href="https://eclipse-dataspaceconnector.github.io/docs/">Docs</a> •
   <a href="https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/issues">Issues</a> •
   <a href="https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/blob/main/LICENSE">License</a> •
   <a href="https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/discussions/1303">Q&A</a>
@@ -27,19 +27,26 @@ Please also refer to:
 - The [GAIA-X](https://gaia-x.eu) project
 - The [Onboarding Guide](onboarding.md)
 
-## Built with
+### Built with
 
 One of the guiding principles in developing the connector is simplicity and keeping the core small and efficient with as
 little external dependencies as possible to avoid version conflicts. We do not want to force any third-party
 dependencies onto our users, so we aim to avoid any of the big frameworks. Of course, if you want to use them, you still
 can add them to your extensions (see: [TBW]). The connector is a plain Java application built with Gradle, but it can be
 embedded into any form of application deployment.
 
-For detailed information about the project, please have a look at our [documentation](/docs/README.md).
+### Documentation
 
-# Getting Started
+Developer documentation can be found under [docs/developer](docs/developer/),
+where the main concepts and decisions are captured as [decision records](docs/developer/decision-records/).
 
-## Add Maven dependencies
+Some more documentation can be found at [extensions](extensions/), [launchers](launchers/) and [samples](samples/).
+
+For detailed information about the whole project, please take a look at our [GitHub pages](https://eclipse-dataspaceconnector.github.io/docs).
+
+## Getting Started
+
+### Add Maven dependencies
 
 Official versions are available through [MavenCentral](https://search.maven.org/search?q=org.eclipse.dataspaceconnector)
 .
@@ -64,7 +71,7 @@ dependencies {
 }
 ```
 
-### Using `SNAPSHOT` versions
+#### Using `SNAPSHOT` versions
 
 In addition, EDC regularly publishes snapshot versions, which are available at Sonatype's snapshot
 repository. In
@@ -98,14 +105,14 @@ Please be aware of the following pitfalls:
 - this may cause unrepeatable builds
 - snapshots are created irregularly, we do not have any fixed publish schedule
 
-### Using release versions
+#### Using release versions
 
 _We plan to have actual release versions starting some time mid 2022. Please check back soon._
 
 
 > For more information about versioning please refer to the [release documentation](docs/developer/releases.md)
 
-## Checkout and build from source
+### Checkout and build from source
 
 The project requires JDK 11+. To get started:
 
@@ -119,14 +126,14 @@ cd DataSpaceConnector
 
 That will build the connector and run unit tests.
 
-## [Optional] Setup your IDE
+### [Optional] Setup your IDE
 
 If you wish to configure your IDE/editor to automatically apply the EDC code style, please
 follow [this guide](styleguide.md).
 
 _Note: the style guide will be checked/enforced in GitHub Actions._
 
-## Run your first connector
+### Run your first connector
 
 Connectors can be started using the concept of "launchers", which are essentially compositions of Java modules defined
 as gradle build files.
@@ -151,11 +158,12 @@ More information about the extension concept can be found here [TBW].
 
 More information about shadowJar can be found [here](https://github.com/johnrengelman/shadow).
 
-## Generate the OpenApi specification
+### Generate the OpenApi specification
 
-Please refer to [this document](./openapi.md).
+Please refer to [this document](docs/developer/openapi.md).
 
-# Directory structure
+
+## Directory structure
 
 ### `spi`
 
@@ -185,8 +193,7 @@ Launchers are essentially connector packages that are runnable. What modules get
 capabilities a connector has) is defined by the `build.gradle.kts` file inside the launcher subdirectory. That's also
 where a Java class containing a `main` method should go. We will call that class a "runtime" and in order for the
 connector to become operational the `runtime` needs to perform several important tasks (="bootstrapping"). For an
-example take a look at
-[this runtime](launchers/basic/src/main/java/org/eclipse/dataspaceconnector/runtime/ConnectorRuntime.java)
+example take a look at [this runtime](samples/other/custom-runtime/src/main/java/org/eclipse/dataspaceconnector/demo/runtime/CustomRuntime.java)
 
 ### `resources/charts`
 
@@ -211,21 +218,22 @@ Contains utility code such as collection utils, string utils and helper classes.
 
 Contains several scripts to deploy a connector in an AKS cluster on Microsoft Azure using Terraform.
 
-## Code style & Patterns
+## Releases
 
-Please refer to the dedicated [style guide](styleguide.md) and the patterns we documented
-in [architecture principles](docs/architecture/architecture-principles.md).
+GitHub releases are listed [here](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/releases).
+Please find more information about releases in our [release approach](docs/developer/releases.md).
 
-## Roadmap
+### Roadmap
 
 See [here](CONTRIBUTING.md#project-and-milestone-planning) for more information about project and
 milestone planning. Scheduled and ongoing milestones are listed
 [here](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/milestones).
 
-## Contributing
+### Tags
 
-See [how to contribute](CONTRIBUTING.md).
+Available tags can be found [here](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/tags).
 
-## Tags
 
-Available tags can be found [here](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector/tags).
+## Contributing
+
+See [how to contribute](CONTRIBUTING.md).

contribution_categories.md

@@ -23,22 +23,28 @@ Note that this covers both what we call the [EDC Core repository](https://github
 It is up to the committers to decide where the code will eventually be hosted in case of adoption.
 
 However, in order to do a preliminary check, please go through the following bullet points:
+
 #### Why should this contribution be adopted?
 Please argue why this feature must be hosted upstream and be maintained by the EDC core team.
+
 #### Could it be achieved with existing functionality? If not, why?
 If there is any existing code that can achieve the same thing with little modification, that is usually the preferable way for the EDC core team. We aim to keep the code succinct and want to avoid similar/duplicate code. Make sure you understand the EDC code base well!
+
 #### Are there multiple use cases or applications who will benefit from the contribution?
 Basically, we want you to motivate who will use that feature and why, thereby arguing the fact that it is well-suited to be adopted in the core code base. One-off features are better suited to be maintained externally. 
+
 #### Can it be achieved without introducing third-party dependencies? If not, which ones?
 EDC is a platform rather than an application, therefore we are extremely careful when it comes to introducing third party libraries. The reasons are diverse: security, license issues and over all JAR weight, just to mention a few important ones.
+
 #### Would this feature limit platform independence in any way? If so, how and why?
 Features that do not work well in clustered environments are difficult to adopt, since EDC is designed from the ground up to be stateless and clusterable. Similarly, features, that have dependencies onto certain operating systems are difficult to argue.
+
 #### Is it going to be a self-contained feature, or would it cut across the entire code base?
 Features that have a large impact on the code base are very complex to thoroughly test, they have a high chance to destabilize the code and require careful inspection. Self-contained features on the other hand are easier to isolate and test.
 
 And on a more general level:
 - does your contribution comply with our [licensing](LICENSE)?
-- does the code adhere to our [styleguide](styleguide.md) and our [architectural principles](docs/architecture/architecture-principles.md)?
+- does the code adhere to our [styleguide](styleguide.md) and our [architectural principles](docs/developer/architecture/architecture-principles.md)?
 - are you willing to accept our [contributing guidelines](CONTRIBUTING.md)?
 - are you prepared to make frequent contributions and help out with maintaining this feature?
 

data-protocols/ids/README.md

@@ -6,9 +6,14 @@ These extensions bridge between EDC core and IDS.
 
 ## Included Extensions
 
-- [data-protocols:ids:ids-spi](../ids-new/ids-spi/README.md)
-- [data-protocols:ids:ids-core](../ids-new/ids-core/README.md)
-- [data-protocols:ids:ids-api-multipart](../ids-new/ids-api-multipart-endpoint-v1/README.md)
+- [data-protocols:ids:ids-api-configuration](ids-api-configuration/)
+- [data-protocols:ids:ids-api-multipart-dispatcher](ids-api-multipart-dispatcher-v1/)
+- [data-protocols:ids:ids-api-multipart-endpoint](ids-api-multipart-endpoint-v1/)
+- [data-protocols:ids:ids-core](ids-core/)
+- [data-protocols:ids:ids-jsonld-serdes-lib](ids-jsonld-serdes-lib/)
+- [data-protocols:ids:ids-spi](ids-spi/)
+- [data-protocols:ids:ids-token-validation](ids-token-validation/)
+- [data-protocols:ids:ids-transform](ids-transform-v1/)
 
 ## IDS Contracts