enhancement(docs): describe what and why ADRs

README.md

@@ -10,17 +10,30 @@
 > [!TIP]
 > For general information about OpenCloud and how to install please visit [OpenCloud on Github](https://github.com/opencloud-eu/) and [OpenCloud GmbH](https://opencloud.eu).
 
-This the main repository of the OpenCloud server. It contains the golang codebase for the backend services.
+This is the main repository of the OpenCloud server.
+It contains the golang codebase for the backend services.
 
 ## Getting Involved
 
-The OpenCloud server is released under [Apache 2.0](https://github.com/opencloud-eu/opencloud/blob/main/LICENSE). The project is very happy to receive contributions in all forms. Start hacking now 😃
+The OpenCloud server is released under [Apache 2.0](https://github.com/opencloud-eu/opencloud/blob/main/LICENSE).
+The project is thrilled to receive contributions in all forms.
+Start hacking now, there are many ways to get involved such as:
 
-### Build OpenCloud
+- Reporting [issues or bugs](https://github.com/opencloud-eu/opencloud/issues)
+- Requesting [features](https://github.com/opencloud-eu/opencloud/issues)
+- [Writing documentation](https://github.com/opencloud-eu/docs)
+- [Writing code or extend our tests](https://github.com/opencloud-eu/opencloud/pulls)
+- [Reviewing code](https://github.com/opencloud-eu/opencloud/pulls)
+- Helping others in the [community](https://app.element.io/#/room/#opencloud:matrix.org)
+
+Every contribution is meaningful and appreciated!
+Please refer to our [Contribution Guidelines](https://github.com/opencloud-eu/opencloud/blob/main/CONTRIBUTING.md) if you want to get started.
+
+## Build OpenCloud
 
 To build the backend, follow these instructions:
 
-Generate the assets needed by e.g. the web UI and the builtin IDP
+Generate the assets needed by e.g., the web UI and the builtin IDP
 
 ``` console
 make generate
@@ -40,10 +53,6 @@ This creates a server configuration (by default in `$HOME/.opencloud`) and start
 
 For more setup- and installation options consult the [Development Documentation](https://docs.opencloud.eu/).
 
-### Contribute
-
-We very much appreciate contributions from the community. Please refer to our [Contribution Guidelines](https://github.com/opencloud-eu/opencloud/blob/main/CONTRIBUTING.md) on how to get started.
-
 ## Technology
 
 Important information for contributors about the technology in use.
@@ -58,4 +67,4 @@ The OpenCloud backend does not use a database. It stores all data in the filesys
 
 ## Security
 
-If you find a security related issue, please contact [security@opencloud.eu](mailto:security@opencloud.eu) immediately.
+If you find a security-related issue, please contact [security@opencloud.eu](mailto:security@opencloud.eu) immediately.

docs/adr/README.md

@@ -0,0 +1,91 @@
+# Architecture Decision Records (ADRs)
+
+## Purpose
+
+This folder contains Architecture Decision Records (ADRs) for the OpenCloud related topics.
+ADRs capture important architectural decisions, their context, alternatives, and rationale.
+
+They help us:
+
+- Document the reasoning behind significant technical choices.
+- Share knowledge and context with current and future team members.
+- Ensure transparency and continuity in our architectural evolution.
+
+## Why Use ADRs?
+
+ADRs provide a structured way to record, discuss, and find architectural decisions over time.
+They make it easier to:
+
+- Understand why certain approaches were chosen.
+- Avoid revisiting previous discussions without context.
+- Onboard new contributors efficiently.
+
+## When to Create an ADR
+
+Not every technical or architectural decision needs a dedicated ADR.
+Use an ADR to document decisions which are significant, such as:
+
+* It substantially affects the architecture, design, or direction of OpenCloud.
+* It involves trade-offs between multiple options.
+* It needs Team consensus or input from multiple stakeholders.
+
+## Writing ADRs
+
+- **Location**: Store all ADRs as Markdown files in this folder.
+- **Format**: Use [Markdown](https://commonmark.org/).
+- **Naming**: Adhere to the naming convention, e.g., `0001-descriptive-title.md`.
+
+### ADR Template
+
+```markdown
+---
+title: "Some Descriptive Title"
+---
+
+* Status: proposed / accepted / deprecated / superseded
+* Deciders: [@user1, @user2]
+* Date: YYYY-MM-DD
+
+Reference: (link to relevant epic, story, issue)
+
+## Context and Problem Statement
+
+Describe the background and why this decision is needed.
+
+## Decision Drivers
+
+Describe the criteria that explains why this decision has to be made.
+
+## Considered Options
+
+Describe single or multiple options that were considered or could be considered.
+
+## Decision Outcome
+
+Describe the chosen option and why it was selected.
+
+### Implementation Steps
+
+Describe the steps needed to implement the decision.
+```
+
+## Process
+
+### New ADRs
+
+1. Write a new ADR as a Markdown file.
+2. Submit it via pull request for review.
+3. Decision is made collaboratively, details will be discussed in the PR, which can lead to further changes.
+4. Update the ADR status once a decision is reached.
+5. Reference ADRs in code, documentation, or issues where relevant.
+
+### Updating ADRs
+
+1. If an ADR needs to be updated, create a new ADR that references the original.
+2. Follow the same process as for new ADRs.
+3. Once accepted, update the status of the original ADR and reference that new ADR.
+
+## References
+
+- [ADR GitHub Template](https://github.com/joelparkerhenderson/architecture_decision_record)
+- [Wikipedia on ADRs](https://en.wikipedia.org/wiki/Architectural_decision)