docs: transfer some documentation from the old website (#5)

eclipse-edc · Sep 19, 2024 · 2fd65ed · 2fd65ed
1 parent 7e38908
commit 2fd65ed
Show file tree

Hide file tree

Showing 9 changed files with 231 additions and 147 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,4 +2,5 @@
 resources/
 node_modules/
 package-lock.json
-.hugo_build.lock
+.hugo_build.lock
+.idea/
diff --git a/README.md b/README.md
@@ -1,91 +1,55 @@
-# Docsy Example
+# eclipse-edc.github.io website
 
-[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy
-site navigation, structure, and more. This **Docsy Example Project** uses the Docsy
-theme component as a hugo module and provides a skeleton documentation structure for you to use.
-You can clone/copy this project and edit it with your own content, or use it as an example.
+This repository contains project-wide documentation.
 
-In this project, the Docsy theme is pulled in as a Hugo module, together with
-its dependencies:
+## GitHub Pages
 
-```console
-$ hugo mod graph
-...
-```
-
-For Docsy documentation, see [Docsy user guide][].
-
-This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][].
-You can view deploy logs from the [deploy section of the project's Netlify
-dashboard][deploys], or this [alternate dashboard][].
-
-This is not an officially supported Google product. This project is currently maintained.
-
-## Using the Docsy Example Project as a template
-
-A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this:
-
-1. Use the dropdown for switching branches/tags to change to the **latest** released tag.
+The documentation files of all EDC repositories are provided with [GitHub Pages](https://docs.github.com/en/pages).
 
-2. Click **Use this template**.
+The pages are deployed from the `/docs` subdirectory to <https://eclipse-edc.github.io/docs>.
 
-3. Select a name for your new project and click **Create repository from template**.
+### Local Deployment
 
-4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL:
+If you want to add content or change configurations, please refer to the [official Docsify documentation](https://docsify.js.org/).
 
-```bash
-git clone --depth 1 https://github.com/me/example.git
+For a local deployment, install [Node.js](https://nodejs.org/), check out this repository, and run Docsify:
+```commandline
+$ git clone https://github.com/eclipse-edc/docs.git
+$ cd docs
+$ npm i docsify-cli -g
+$ docsify serve docs
 ```
 
-You can now edit your own versions of the site’s source files.
-
-If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
+## Contributing
 
-```bash
-npm install
-```
+See [how to contribute](CONTRIBUTING.md).
 
 ## Running the website locally
 
 Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
 You can find out more about how to install Hugo for your environment in our
 [Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
 
-Once you've made your working copy of the site repo, from the repo root folder, run:
-
 ```bash
 hugo server
 ```
 
 ## Running a container locally
 
-You can run docsy-example inside a [Docker](https://docs.docker.com/)
-container, the container runs with a volume bound to the `docsy-example`
-folder. This approach doesn't require you to install any dependencies other
-than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
-Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
-on Linux.
+You can run the website inside a [Docker](https://docs.docker.com/)
+container, the container runs with a volume bound to the root folder.
 
 1. Build the docker image
 
    ```bash
-   docker-compose build
+   docker compose up --build`
    ```
 
-1. Run the built image
-
-   ```bash
-   docker-compose up
-   ```
-
-   > NOTE: You can run both commands at once with `docker-compose up --build`.
-
-1. Verify that the service is working.
+2. Verify that the service is working.
 
    Open your web browser and type `http://localhost:1313` in your navigation bar,
-   This opens a local instance of the docsy-example homepage. You can now make
-   changes to the docsy example and those changes will immediately show up in your
-   browser after you save.
+   This opens a local instance of the homepage. You can now make
+   changes to the docs and those changes will immediately show up in your browser after you save.
 
 ### Cleanup
 
@@ -94,91 +58,6 @@ To stop Docker Compose, on your terminal window, press **Ctrl + C**.
 To remove the produced images run:
 
 ```bash
-docker-compose rm
+docker compose rm
 ```
 For more information see the [Docker Compose documentation][].
-
-## Using a local Docsy clone
-
-Make sure your installed go version is `1.18` or higher.
-
-Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your site's root folder.
-
-```shell
-cd root-of-your-site
-git clone --branch v0.7.2 https://github.com/google/docsy.git ../docsy
-```
-
-Now run:
-
-```shell
-HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**"
-```
-
-or, when using npm, prepend `local` to the script you want to invoke, e.g.:
-
-```shell
-npm run local serve
-```
-
-By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are  now immediately picked up (hot reload), you can instantly see the effect of your local edits.
-
-In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `docsy.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`:
-
-```toml
-[module]
-  workspace = "docsy.work"
-```
-
-Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the two trailing comment characters '//' so that this line takes effect.
-
-## Troubleshooting
-
-As you run the website locally, you may run into the following error:
-
-```console
-$ hugo server
-WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information.
-Start building sites …
-hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
-Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
-Built in 27 ms
-```
-
-This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.7.0`, hugo version `0.110.0` or higher is required.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may be confronted with the following error:
-
-```console
-$ hugo server
-
-INFO 2021/01/21 21:07:55 Using config file:
-Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
-Built in 288 ms
-Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
-```
-
-This error occurs if you have not installed the extended version of Hugo.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may encounter the following error:
-
-```console
-$ hugo server
-
-Error: failed to download modules: binary with name "go" not found
-```
-
-This error occurs if you have not installed the `go` programming language on your system.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
-
-
-[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
-[deploys]: https://app.netlify.com/sites/docsy-example/deploys
-[Docsy user guide]: https://docsy.dev/docs
-[Docsy]: https://github.com/google/docsy
-[example.docsy.dev]: https://example.docsy.dev
-[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
-[Netlify]: https://netlify.com
-[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/
diff --git a/content/en/_index.md b/content/en/_index.md
@@ -14,7 +14,6 @@ EDC provides highly customizable components for creating control planes, data pl
 and federated data catalogs. Backed by leading companies and cloud providers, EDC gives developers the tools they need
 to deliver innovative solutions for data exchange networks.
 </p>
-<p class="lead mt-5"><b>Site still under construction, please refer to <a href="https://eclipse-edc.github.io/docs">https://eclipse-edc.github.io/docs</a> for currently released documentation.</b></p>
 
 <img height="500px" width="600px" src="images/edc.schematic.svg">
 {{< /blocks/cover >}}

diff --git a/content/en/documentation/adoption.md b/content/en/documentation/adoption.md
@@ -0,0 +1,91 @@
+---
+title: Getting adopted
+weight: 100
+---
+
+This document is intended as guideline for contributors who either already have implemented a feature, e.g. an
+extension, or intend to do so, and are looking for ways to upstream that feature into the EDC.
+
+There are currently two possible levels of adoption for the EDC project:
+
+1. incorporate a feature as core EDC component
+2. reference a feature as "friend"
+
+## Get referenced as "friend"
+
+This means we will add a link to our [known friends](known-friends.md) list, where we reference projects and features
+that we are aware of. These are repositories that have no direct affiliation with EDC and are hosted outside the
+`eclipse-edc` GitHub organization. We call this a "friend" of EDC (derived from the C++ [
+`friend class` concept](https://en.cppreference.com/w/cpp/language/friend)).
+In order to become a "friend" of EDC, we do a quick scan of the code base to make sure it does not contain anything
+offensive, or that contradicts our code of conduct, ethics or other core OSS values.
+
+The EDC core team does not maintain or endorse "friend" projects in any way, nor is it responsible for it, but we do
+provide a URL list to make it easier for other developers to find related projects and get an overview of the EDC market
+spread.
+
+This is the easiest way to "get in" and will be the suitable form of adoption for _most_ features and projects.
+
+## Get adopted in EDC core
+
+This means the contribution gets added to the EDC code base, and is henceforth maintained by the EDC core team. The
+barrier of entry for this is much higher than for "friends", and a more in-depth review of the code will be performed.
+
+Note that this covers both what we call the [EDC Core repository](https://github.com/eclipse-edc/Connector) and any
+current or future repositories in the `eclipse-edc` GitHub organization.
+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](https://github.com/eclipse-edc/eclipse-edc.github.io/blob/main/LICENSE)?
+- does the code adhere to our [contributors guidelines](documentation/for-contributors/guidelines)?
+- are you willing to accept our [contributing guidelines](https://github.com/eclipse-edc/eclipse-edc.github.io/blob/main/CONTRIBUTING.md)?
+- are you prepared to make frequent contributions and help out with maintaining this feature?
+
+When you submit an application for adopting a feature, _be prepared to answer all of them in an exhaustive and coherent
+way_!
+
+Note that even if all the aforementioned points are answered satisfactorily, **the EDC core team reserves the right to
+ultimately decide whether a feature will get adopted or not.**
+
+## Submitting an application
+
+Please open in issue using the [adoption request](https://github.com/eclipse-edc/.github/blob/main/.github/ISSUE_TEMPLATE/adoption_request.md)
+template, fill out all the sections to the best of your knowledge and wait to hear back from the EDC core team. We will
+comment in the issue, or reach out to you directly. Be aware that omitting sections from the application will greatly
+diminish the chance of approval.
diff --git a/content/en/documentation/committers.md b/content/en/documentation/committers.md
@@ -0,0 +1,48 @@
+---
+title: Committers
+weight: 200
+---
+
+Committers decide what code goes into the code base, they decide how a project builds, and they ultimately decide what
+gets delivered to the adopter community. With awesome power, comes awesome responsibility, and
+so [the Open Source Rules of Engagement](https://www.eclipse.org/projects/dev_process/#2_1_Open_Source_Rules_of_Engagement)
+described by [the Eclipse Foundation Development Process](https://www.eclipse.org/projects/dev_process/) puts
+meritocracy on equal footing with transparency and openness: becoming a committer isn’t necessarily hard, but it does
+require a demonstration of merit:
+
+- Operate in an open, transparent, and meritocratic manner;
+- Write code (and other project content) and push it directly into the project’s source code repository;
+- Review contributions (merge and pull requests) from contributors;
+- Engage in the Intellectual Property Due Diligence Process;
+- Vote in committer and project lead elections;
+- Engage in the project planning process; and
+- Otherwise represent the interests of the open source project.
+
+For Eclipse projects (and the open source world in general), committers are the ones who hold the keys. Committers are
+either appointed at the time of project creation or elected by the existing project team.
+
+## Inactive Committers
+
+It's inevitable, but there are times when someone shifts focus, changes jobs, or retires from a particular area of the
+project (for a period of time). These people may be experts in certain areas of the codebase or representatives persons
+for certain topics but can no longer devote the time necessary to take on the responsibilities of a Committer role.
+However, being a Committer within an Eclipse Foundation project comes with an elevated set of permissions. These
+capabilities should not be used by those that are not familiar with the current state of the EDC project.
+
+From time to time, it is necessary to prune the internal organization and remove inactive folks. A core principle in
+maintaining a healthy community is encouraging active participation. Those listed as a Committer of the project have a
+higher activity requirement, as they directly impact the ability of others to contribute. Therefore, members who have
+been absent from the project for a long period of time and have had no activity will be retired from their role as
+Committers.
+in the EDC and will be required to go through the meritocratic process again after re-familiarizing themselves with the
+current state. Committers, that can no longer devote the time are kindly asked to follow the retirement process of the
+Eclipse Foundation.
+
+According to the EF rules, before retiring a Committer, the project’s community will be informed of the change and the
+Committer must be given a chance to defend retaining their status via the project’s dev-list.
+
+To honor the contributions, retired Committers are listed as Historic Committers on the
+project’s [Who’s Involved page](https://projects.eclipse.org/projects/technology.edc/who). When a Committer returns to
+being more active in that area, they may be promoted back on the decision of the Committers' committee. However, after
+an extended period away from the project with no activity those would need demonstrably have to re-familiarize
+themselves with the current state before being able to contribute effectively.
diff --git a/content/en/documentation/for-contributors/_index.md b/content/en/documentation/for-contributors/_index.md
@@ -237,7 +237,7 @@ principles](../../contributing/coding-principles.md).
 A frequent subject of critique in pull requests is logging. Spurious and very verbose log lines like "Entering/Leaving
 method X" or "Performing action Z" should be avoided because they pollute the log output and don't contribute any value.
 
-Please find detailed information about logging [here](../../logging.md).
+Please find detailed information about logging [here](logging.md).
 
 ### 5.2 Testing best practices