From 20653b6b95e6d4f6f5e6f20dd7ce9a89cc1ac7c8 Mon Sep 17 00:00:00 2001 From: ndr_brt Date: Fri, 20 Sep 2024 13:17:17 +0200 Subject: [PATCH] docs: cleanup README --- README.md | 190 +++++------------------------------------------------- 1 file changed, 15 insertions(+), 175 deletions(-) diff --git a/README.md b/README.md index 7e0c3f964e6..944677b3991 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,21 @@ -

-
- EDC Connector -
-

- -
- - Tests status - - - Coverage - - - Discord chat - - - Version - - - License - -
-
- - License - - - License - -
- - -### 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. - -### Documentation - -Developer documentation can be found under [docs/developer](docs/developer/README.md), -where the main concepts and decisions are captured as [decision records](docs/developer/decision-records/README.md). - -Some more documentation can be found at [extensions](extensions/README.md), [launchers](launchers/README.md) and -[the samples repository](https://github.com/eclipse-edc/Samples). - -For detailed information about the whole project, please take a look at -our [GitHub pages](https://eclipse-edc.github.io/docs). - -## Getting Started - -### Onboarding and first steps - -If you are not yet familiar with the EDC nomenclature, we strongly advise reading the -[documentation](https://eclipse-edc.github.io/docs/#/) and/or watching the -[introductory videos](https://www.youtube.com/@eclipsedataspaceconnector9622/featured). - -#### Samples - -The [Samples repository](https://github.com/eclipse-edc/Samples) provides a set of examples for getting familiar with -the EDC framework and learning how to set up and use a connector. The samples begin with the very basics (e.g. learning -how to write an extension or use a configuration file) and then move on to more complex scenarios (e.g. performing -different data transfers). More samples will be added in the future, so be sure to check back regularly. - -### Add Maven dependencies - -Official versions are available through [MavenCentral](https://search.maven.org/search?q=org.eclipse.edc) -. -Please add the following instructions in your `build.gradle[.kts]` file (if not already present): - -```kotlin -repositories { - mavenCentral() - // ... other maven repos -} -``` - -We **strongly** recommend to use official versions and only switch to snapshots if there is a clear need to do so, or -you've been instructed to do so, e.g. to verify a bugfix. - -All artifacts are under the `org.eclipse.edc` group id, for example: - -```kotlin -dependencies { - implementation("org.eclipse.edc:spi:core-spi:<>") - // any other dependencies -} -``` - -#### Using `SNAPSHOT` versions - -In addition, EDC regularly publishes snapshot versions, which are available at Sonatype's snapshot -repository. In -order to add them to your build configuration, simply add this: - -```kotlin -repositories { - mavenCentral() - maven { - url = uri("https://oss.sonatype.org/content/repositories/snapshots/") - } - // any other repos -} -``` - -Then you can add snapshot dependencies by simply using the `-SNAPSHOT` version suffix: - -```kotlin -dependencies { - implementation("org.eclipse.edc:spi:core-spi:0.10.0-SNAPSHOT") - // any other dependencies -} -``` - -You may check MavenCentral for a comprehensive list of all official versions. +# EDC connector -Please be aware of the following pitfalls: +[![documentation](https://img.shields.io/badge/documentation-8A2BE2?style=flat-square)](https://eclipse-edc.github.io) +[![discord](https://img.shields.io/badge/discord-chat-brightgreen.svg?style=flat-square&logo=discord)](https://discord.gg/n4sD9qtjMQ) +[![latest version](https://img.shields.io/maven-central/v/org.eclipse.edc/boot?logo=apache-maven&style=flat-square&label=latest%20version)](https://search.maven.org/artifact/org.eclipse.edc/boot) +[![license](https://img.shields.io/github/license/eclipse-edc/Connector?style=flat-square&logo=apache)](https://www.apache.org/licenses/LICENSE-2.0) +
+[![build](https://img.shields.io/github/actions/workflow/status/eclipse-edc/Connector/verify.yaml?branch=main&logo=GitHub&style=flat-square&label=ci)](https://github.com/eclipse-edc/Connector/actions/workflows/verify.yaml?query=branch%3Amain) +[![snapshot build](https://img.shields.io/github/actions/workflow/status/eclipse-edc/Connector/trigger_snapshot.yml?branch=main&logo=GitHub&style=flat-square&label=snapshot-build)](https://github.com/eclipse-edc/Connector/actions/workflows/trigger_snapshot.yml) +[![nightly build](https://img.shields.io/github/actions/workflow/status/eclipse-edc/Release/nightly.yaml?branch=main&logo=GitHub&style=flat-square&label=nightly-build)](https://github.com/eclipse-edc/Release/actions/workflows/nightly.yaml) -- snapshots are by definition unstable - every new snapshot replaces an old one -- this may cause unrepeatable builds -- snapshots are created irregularly, we do not have any fixed publish schedule +--- -#### Using release versions +## Documentation -_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](https://github.com/eclipse-edc/.github/blob/main/docs/developer/releases.md) - -### Checkout and build from source - -The project requires JDK 11+. To get started: - -``` shell -git clone git@github.com:eclipse-edc/Connector.git - -cd Connector - -./gradlew clean build -``` - -That will build the connector and run unit tests. - -### [Optional] Setup your IDE - -If you wish to configure your IDE/editor to automatically apply the EDC code style, please -follow [this guide](https://github.com/eclipse-edc/.github/blob/main/contributing/styleguide.md). - -_Note: the style guide will be checked/enforced in GitHub Actions._ - -### Generate the OpenApi specification - -Please refer to [this document](docs/developer/openapi.md). +Base documentation can be found on the [documentation website](https://eclipse-edc.github.io). \ +Developer documentation can be found under [docs/developer](docs/developer/README.md), \ +where the main concepts and decisions are captured as [decision records](docs/developer/decision-records/README.md). ## Directory structure @@ -199,21 +54,6 @@ example take a look at Contains implementations for communication protocols a connector might use, such as DSP. -## Releases - -GitHub releases are listed [here](https://github.com/eclipse-edc/Connector/releases). -Please find more information about releases in our [release approach](https://github.com/eclipse-edc/docs/blob/main/developer/releases.md). - -### Roadmap - -See [here](https://github.com/eclipse-edc/.github/blob/main/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-edc/Connector/milestones). - -### Tags - -Available tags can be found [here](https://github.com/eclipse-edc/Connector/tags). - ## Contributing -See [how to contribute](https://github.com/eclipse-edc/.github/blob/main/CONTRIBUTING.md). +See [how to contribute](https://github.com/eclipse-edc/eclipse-edc.github.io/blob/main/CONTRIBUTING.md).