From 950b9d7ba5b30dd13eeb2d58572048253ca5acec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wolf-Martell=20Montw=C3=A9?= Date: Thu, 5 Oct 2023 17:08:50 +0200 Subject: [PATCH 1/4] Add ADR readme and template --- README.md | 10 +++++ docs/architecture/adr/0000-adr-template.md | 29 ++++++++++++ docs/architecture/adr/README.md | 51 ++++++++++++++++++++++ 3 files changed, 90 insertions(+) create mode 100644 docs/architecture/adr/0000-adr-template.md create mode 100644 docs/architecture/adr/README.md 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/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. From bec885475de5667bb517176986a851758b6af910 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wolf-Martell=20Montw=C3=A9?= Date: Thu, 5 Oct 2023 17:10:52 +0200 Subject: [PATCH 2/4] Add ADR 0001 about Java to Kotlin switch --- .../adr/0001-switch-from-java-to-kotlin.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/architecture/adr/0001-switch-from-java-to-kotlin.md 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. From be152a49ca97a7465fb1721ae1bfe9ee246ba8ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wolf-Martell=20Montw=C3=A9?= Date: Thu, 5 Oct 2023 17:11:57 +0200 Subject: [PATCH 3/4] Add ADR 0002 about wrapping the material components in an atomic design system --- ...rial-components-in-atomic-design-system.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/architecture/adr/0002-ui-wrap-material-components-in-atomic-design-system.md 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..ab3c0cea955 --- /dev/null +++ b/docs/architecture/adr/0002-ui-wrap-material-components-in-atomic-design-system.md @@ -0,0 +1,36 @@ +# 0002 - UI - Wrap Material Components in Atomic Design System + +## Status + +- **Proposed** + +## Context + +As we continue developing our Jetpack Compose application, we find a need to increase the consistency, reusability, +and maintainability of our UI components. Currently, we are using Material components directly throughout our +application. This leads to a lack of uniformity and increases the complexity of changes as the same modifications +must be implemented multiple times across different screens. + +## Decision + +We are proposing to create a new atomic design system where Material components are wrapped into our own 'atomic' +components. For instance, we would have components such as `AtomicButton`, `AtomicText`, etc. These atomic components +will encapsulate Material components with predefined styles and behaviors. + +This approach will be taken further to develop more complex 'molecule' and 'organism' components by combining these +atomic components. We will also define 'templates' as layout structures and 'pages' as specific instances of these +templates to build a complete user interface. + +## Consequences + +- **Positive Consequences** + + - Increased reusability of components across the application, reducing code duplication. + - More consistent UI 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. From 89da8fec51858774d9cd08dbb1a0f715e37c2493 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wolf-Martell=20Montw=C3=A9?= Date: Fri, 6 Oct 2023 11:04:49 +0200 Subject: [PATCH 4/4] Changed ADR 0002 from proposed to accepted --- ...rial-components-in-atomic-design-system.md | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) 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 index ab3c0cea955..51b00cf6cd2 100644 --- 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 @@ -2,31 +2,30 @@ ## Status -- **Proposed** +- **Accepted** ## Context -As we continue developing our Jetpack Compose application, we find a need to increase the consistency, reusability, -and maintainability of our UI components. Currently, we are using Material components directly throughout our -application. This leads to a lack of uniformity and increases the complexity of changes as the same modifications -must be implemented multiple times across different screens. +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 -We are proposing to create a new atomic design system where Material components are wrapped into our own 'atomic' -components. For instance, we would have components such as `AtomicButton`, `AtomicText`, etc. These atomic components -will encapsulate Material components with predefined styles and behaviors. - -This approach will be taken further to develop more complex 'molecule' and 'organism' components by combining these -atomic components. We will also define 'templates' as layout structures and 'pages' as specific instances of these -templates to build a complete user interface. +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 across the entire application. + - 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**