diff --git a/README.md b/README.md index 25b085a2e2..b347e180f8 100644 --- a/README.md +++ b/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. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000000..d40ae96f91 --- /dev/null +++ b/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**: 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)