diff --git a/README.md b/README.md index 5768dbb7996..430a448efec 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,16 @@ Any contributions, large or small, major features, bug fixes, unit/integration t but will be thoroughly reviewed and discussed. Please make sure you read the [Code Style Guidelines](https://github.com/thundernest/k-9/wiki/CodeStyle). +### Architecture Decision Records (ADR) + +We use [Architecture Decision Records](https://adr.github.io/) to document the architectural decisions made in the +development of K-9 Mail. You can find them in the [`docs/architecture/adr`](docs/architecture/adr) directory. + +For more information about our ADRs, please see the [ADRs README](docs/architecture/adr/README.md). + +We encourage team members and contributors to read through our ADRs to understand the architectural decisions that +have shaped this project so far. Feel free to propose new ADRs or suggest modifications to existing ones as needed. + ## Communication Aside from discussing changes in [pull requests](https://github.com/thundernest/k-9/pulls) and diff --git a/docs/architecture/adr/0000-adr-template.md b/docs/architecture/adr/0000-adr-template.md new file mode 100644 index 00000000000..5d752b15f26 --- /dev/null +++ b/docs/architecture/adr/0000-adr-template.md @@ -0,0 +1,29 @@ +# [NNNN] - [Descriptive Title in Title Case] + +## Status + + + +- **Status** + +## Context + + + +## Decision + + + +## Consequences + + + +- **Positive Consequences** + + - consequence 1 + - consequence 2 + +- **Negative Consequences** + + - consequence 1 + - consequence 2 diff --git a/docs/architecture/adr/0001-switch-from-java-to-kotlin.md b/docs/architecture/adr/0001-switch-from-java-to-kotlin.md new file mode 100644 index 00000000000..8ae1e5aa044 --- /dev/null +++ b/docs/architecture/adr/0001-switch-from-java-to-kotlin.md @@ -0,0 +1,32 @@ +# 0001 - Switch from Java to Kotlin + +## Status + +- **Accepted** + +## Context + +We've been using Java as our primary language for Android development. While Java has served us well, it has certain +limitations in terms of null safety, verbosity, functional programming, and more. Kotlin, officially supported by +Google for Android development, offers solutions to many of these issues and provides more modern language features +that can improve productivity, maintainability, and overall code quality. + +## Decision + +Switch our primary programming language for Android development from Java to Kotlin. This will involve rewriting our +existing Java codebase in Kotlin and writing all new code in Kotlin. To facilitate the transition, we will gradually +refactor our existing Java codebase to Kotlin. + +## Consequences + +- **Positive Consequences** + + - Improved null safety, reducing potential for null pointer exceptions. + - Increased code readability and maintainability due to less verbose syntax. + - Availability of modern language features such as coroutines for asynchronous programming, and extension functions. + - Officially supported by Google for Android development, ensuring future-proof development. + +- **Negative Consequences** + + - The process of refactoring existing Java code to Kotlin can be time-consuming. + - Potential for introduction of new bugs during refactoring. diff --git a/docs/architecture/adr/0002-ui-wrap-material-components-in-atomic-design-system.md b/docs/architecture/adr/0002-ui-wrap-material-components-in-atomic-design-system.md new file mode 100644 index 00000000000..51b00cf6cd2 --- /dev/null +++ b/docs/architecture/adr/0002-ui-wrap-material-components-in-atomic-design-system.md @@ -0,0 +1,35 @@ +# 0002 - UI - Wrap Material Components in Atomic Design System + +## Status + +- **Accepted** + +## Context + +As we continued developing our Jetpack Compose application, we found a need to increase the consistency, reusability, +and maintainability of our user interface (UI) components. We have been using Material components directly throughout our +application. This lead to a lack of uniformity and increases the complexity of changes as the same modifications had to +be implemented multiple times across different screens. + +## Decision + +To address these challenges, we've decided to adopt an +[Atomic Design System](../../../core/ui/compose/designsystem/README.md) as a foundation for our application UI. +This system encapsulates Material components within our [own components](../../../core/ui/compose/designsystem/), +organized into categories of _atoms_, _molecules_, and _organisms_. We also defined _templates_ as layout structures +that can be flexibly combined to construct _pages_. These components collectively form the building blocks that we are +using to construct our application's UI. + +## Consequences + +- **Positive Consequences** + + - Increased reusability of components across the application, reducing code duplication. + - More consistent UI and uniform styling across the entire application. + - Improved maintainability, as changes to a component only need to be made in one place. + +- **Negative Consequences** + + - Initial effort and time investment needed to implement the atomic design system. + - Developers need to adapt to the new system and learn how to use it effectively. + - Potential for over-complication if simple components are excessively broken down into atomic parts. diff --git a/docs/architecture/adr/README.md b/docs/architecture/adr/README.md new file mode 100644 index 00000000000..e57ff4fa87a --- /dev/null +++ b/docs/architecture/adr/README.md @@ -0,0 +1,51 @@ +# Architecture Decision Records + +This [folder](/docs/architecture/adr) contains the architecture decision records (ADRs) for our project. + +ADRs are short text documents that serve as a historical context for the architecture decisions we make over the +course of the project. + +## What is an ADR? + +An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along +with its context and consequences. ADRs record the decision making process and allow others to understand the +rationale behind decisions, providing insight and facilitating future decision-making processes. + +## Format of an ADR + +We adhere to Michael Nygard's [ADR format proposal](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), +where each ADR document should contain: + +1. **Title**: A short descriptive name for the decision. +2. **Status**: The current status of the decision (proposed, accepted, rejected, deprecated, superseded) +3. **Context**: The context that motivates this decision. +4. **Decision**: The change that we're proposing and/or doing. +5. **Consequences**: What becomes easier or more difficult to do and any risks introduced as a result of the decision. + +## Creating a new ADR + +When creating a new ADR, please follow the provided [ADR template file](0000-adr-template.md) and ensure that your +document is clear and concise. + +## Directory Structure + +The ADRs will be stored in a directory named `docs/adr`, and each ADR will be a file named `NNNN-title-with-dashes.md` +where `NNNN` is a four-digit number that is increased by 1 for every new adr. + +## ADR Life Cycle + +The life cycle of an ADR is as follows: + +1. **Proposed**: The ADR is under consideration. +2. **Accepted**: The decision described in the ADR has been accepted and should be adhered to, unless it is superseded by another ADR. +3. **Rejected**: The decision described in the ADR has been rejected. +4. **Deprecated**: The decision described in the ADR is no longer relevant due to changes in system context. +5. **Superseded**: The decision described in the ADR has been replaced by another decision. + +Each ADR will have a status indicating its current life-cycle stage. An ADR can be updated over time, either to change +the status or to add more information. + +## Contributions + +We welcome contributions in the form of new ADRs or updates to existing ones. Please ensure all contributions follow +the standard format and provide clear and concise information.