Merge pull request #7221 from thundernest/add_architecture_decision_r…

…ecords

Add architecture decision records

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

docs/architecture/adr/0000-adr-template.md

@@ -0,0 +1,29 @@
+# [NNNN] - [Descriptive Title in Title Case]
+
+## Status
+
+<!-- [Status from the options: proposed, accepted, rejected, deprecated, superseded] -->
+
+- **Status**
+
+## Context
+
+<!-- [Description of the context and problem statement that the decision is addressing. It should contain any relevant factors that influenced the decision.] -->
+
+## Decision
+
+<!-- [Description of the decision that was made. Detail the change that will be implemented.] -->
+
+## Consequences
+
+<!-- [Explanation of the consequences of the decision. This includes both the positive and negative effects, and any potential risks.] -->
+
+- **Positive Consequences**
+
+  - consequence 1
+  - consequence 2
+
+- **Negative Consequences**
+
+  - consequence 1
+  - consequence 2

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.

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.

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.