mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-02-04 19:19:03 -06:00
Code Issues Packages Projects Releases Wiki Activity

enhancement(docs): describe what and why ADRs

Browse Source
This commit is contained in:
fschade
2025-09-18 12:23:22 +02:00
parent 0410c150a0
commit 5f675ee678
2 changed files with 109 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@@ -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.

91
docs/adr/README.md Normal file
View File

@@ -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**: Use a consistent 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)