eclipse-edc / docs

EDC documentation

EDC Documentation

This repository contains project-wide documentation.

• How to contribute
  • Get referenced as "friend"
  • How to create a PR
• Developer documentation
  • Coding principles
  • Styleguide
  • Handbook
  • Templates
• Project-wide decision records
• Committer guidelines
• List of adoptions

GitHub Pages

The documentation files of all EDC repositories are provided with GitHub Pages.

The pages are deployed from the /docs subdirectory to https://eclipse-edc.github.io/docs.

Local Deployment

If you want to add content or change configurations, please refer to the official Docsify documentation.

For a local deployment, install Node.js, check out this repository, and run Docsify:

$ git clone https://github.com/eclipse-edc/docs.git
$ cd docs
$ npm i docsify-cli -g
$ docsify serve docs

Contributing

See how to contribute.

docs's Issues

Create an API Maturity Level and Deprecation Policy

Feature Request

To promote consistency across EDC repos and better enable downstream projects to build on EDC, we need clearly defined API maturity levels and a deprecation policy. This will be done as a Decision Record.

Which Areas Would Be Affected?

All EDC repositories.

Why Is the Feature Desired?

Consistency and communication for downstream projects.

Remove RegistrationService from docs

Feature Request

Remove RegistrationService as it was archived, and it will be embed in MVD

Which Areas Would Be Affected?

e.g., DPF, CI, build, transfer, etc.

Why Is the Feature Desired?

Are there any requirements?

Solution Proposal

If possible, provide a (brief!) solution proposal.

Broken link in documentation

Bug Report

Describe the Bug

On https://eclipse-edc.github.io/docs/#/README the link known friends is broken

Checkstyle XML config file link is broken

Bug Report

Describe the Bug

The link to the Checkstyle XML Document on the styleguide page is broken.

Steps to Reproduce

Steps to reproduce the behavior:

1. Go to 'https://eclipse-edc.github.io/docs/#/submodule/Connector/styleguide'
2. Click on 'config written in XML'
3. See 404 error

Possible Implementation

Remove the "#/" from the link.

Links to resources related to .github are dead

Bug Report

Describe the Bug

• scan-pull-request.yml in pr_etiquette can not be rendered due to the limitation of docsify.
• link to "adoption request template" in adoption is 404 due to file relocation in .github.

Links to documentation of Samples are 404

Bug Report

Describe the Bug

Hyperlinks to docs of Samples are 404 in Developer's Handbook.

Detailed Description

Since docs is submodule of docs itself, relative link like ../docs/samples points to empty directory. Samples as submodule is located under /samples.

Possible Implementation

cleanup DSC references

Feature Request

Currently in the main documentation page there's a paragraph about the difference between EDC and DSC, I think that's not really necessary anymore, especially after the DSP took over
https://github.com/eclipse-edc/docs/tree/main/docs#statement-edc-vs-dsc

Removing that part will make the page shorter and easier to understand

Which Areas Would Be Affected?

e.g., DPF, CI, build, transfer, etc.

Why Is the Feature Desired?

Are there any requirements?

Solution Proposal

If possible, provide a (brief!) solution proposal.

Edit link in readme

Bug Report

Describe the Bug

In the readme file Line 22, the links lead undefined page.

Expected Behavior

It leads to the available link file.

Possible Implementation

Update the link to CONTRIBUTING.md.

Add gradle plugin repo to ToC

Feature Request

Add gradle plugin repo as submodule.

Why Is the Feature Desired?

To also link the provided documentation there.

Solution Proposal

Add submodule, link it in sidebar.

Type of Issue

improvement

Checklist

• assigned appropriate label?
• Do NOT select a milestone or an assignee!

Add guide for local deployment

Feature Request

Add a short "getting started" section to the README of this repo.

Why Is the Feature Desired?

For interested developers that want to deploy and/or change the documentation locally (request in #1931).

Solution Proposal

Provide basic Docsify guidance.

Type of Issue

documentation

Checklist

• assigned appropriate label?
• Do NOT select a milestone or an assignee!

Patterns/guidelines for deployment of EDC components in participant infra

Feature Request

Most of the components introduces in the EDC project are to be deployed by each dataspace participant (Control/Data planes, IdentityHub, Catalog...). These components expose routes for external communication and for exchanging the data.

Depending on the security regulations (firewall, API gateway....) in each participants infrastructures, deploying these components in a security-compliant way might be complex.

Here we aim at providing guidelines and typical deployment topology(ies) for the different EDC components.

Which Areas Would Be Affected?

docs.

`Open API Specification` link points to the old endpoint

Bug Report

Describe the Bug

The "Open API Specification" link here doesn't work
https://eclipse-dataspacecomponents.github.io/docs/#/hands-on.md

Possible Implementation

update the url

Enhance GitHub Pages build

Feature Request

Move the docs folder to a dedicated branch, e.g., gh-pages or docsify, and build the GitHub Pages from there.

Which Areas Would Be Affected?

docs

Why Is the Feature Desired?

Simplify the structure of this repo. The docs folder does not contain any documentation content and can go into a dedicated build branch.

Solution Proposal

1. Create branch from current main. Remove docs folder from main.
2. Adapt GitHub pages settings. (admin required)
3. Update the GH Action to merge into the build branch:

# update-submodules.yaml

PULL_REQUEST_BRANCH: "docsify"

Missing Pages, Broken Links, 404 Errors

Bug Report

Describe the Bug

(This is just one example. See the comments for further pages and infos.)

The following page is shown in the menu ("Best Practices") but leads to a "Page not found" error:
https://eclipse-edc.github.io/docs/#/submodule/Connector/docs/developer/best-practices

Expected Behavior

A best practices page is shown.

Observed Behavior

A 404 error is shown.

Steps to Reproduce

Steps to reproduce the behavior:

1. Visit https://eclipse-edc.github.io/docs/#/submodule/Connector/docs/developer/best-practices
2. See error

Context Information

Add any other context about the problem here.

• Usage of published version at https://eclipse-edc.github.io/

Detailed Description

./.

Possible Implementation

./.

Add Trust Framework Adoption repo to documentation

Feature Request

Add Trust Framework Adoption repo as submodule.

Why Is the Feature Desired?

To also link the provided documentation there.

Solution Proposal

Add submodule, link it in sidebar.

Type of Issue

improvement

Checklist

• assigned appropriate label?
• Do NOT select a milestone or an assignee!

Add "developer" and "decision records" links on sidebar

Feature Request

Currently jumping to the developer documentation for specific repository component could be cumbersome as it will require to go to the main README.md and find the link to the doc.

Some links could be added to the sidebar to make this easier.

Which Areas Would Be Affected?

sidebar

Provide a components overview

Feature Request

Add documentation about components and their relations.

Which Areas Would Be Affected?

root

Why Is the Feature Desired?

See https://github.com/orgs/eclipse-edc/discussions/61

Solution Proposal

• Two line description of components
• Diagram to visualize the relations of the components

Link in sidebar at "Getting Started".

Provide architecture documentation

Feature Request

Add documentation targeting software architects.

Which Areas Would Be Affected?

developer documentation

Why Is the Feature Desired?

See https://github.com/orgs/eclipse-edc/discussions/61

Solution Proposal

Possible content:

• Architecture overview
• List of features
• Used standards

This should be linked in the sidebar at "Getting Started".

doc: Add a decision record on the direction of decentralized identity in the EDC

We need to add a Decision Record detailing the future technical direction of decentralized identity in the EDC.