docs: add engineering section (#11072)

Author: wmontwe

.github/pull_request_template.md

@@ -2,8 +2,9 @@
 
 ### Prior to submitting a pull request, please familiarize yourself with...
 
+- Our [Engineering docs](https://github.com/thunderbird/thunderbird-android/tree/main/docs/engineering)
+  - Including the [Architecture Decision Records](https://github.com/thunderbird/thunderbird-android/tree/main/docs/engineering/adr)
 - Our [Architecture docs](https://github.com/thunderbird/thunderbird-android/tree/main/docs/architecture)
-  - Including the [Architecture Design Records](https://github.com/thunderbird/thunderbird-android/tree/main/docs/architecture/adr)
 - Read [Mozilla’s Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/)
 - Check out our [contribution code quality guides](https://github.com/thunderbird/thunderbird-android/tree/main/docs/contributing), especially our [git commit guide](https://github.com/thunderbird/thunderbird-android/blob/main/docs/contributing/git-commit-guide.md), which can also help you write your pull request title
 
@@ -20,6 +21,7 @@ As always, thank you for the contribution!
 ## Contribution Summary
 
 Linked Issue/Ticket: 
+RFC / Technical Design (if applicable):
 
 #### Description
 
@@ -45,4 +47,5 @@ Select **one** of the following (mandatory)
 - [ ] This contribution adheres to the existing codestyle (run `gradlew spotlessCheck` to check and `gradlew spotlessApply` to format your source code; will be checked by CI).
 - [ ] This contribution does not break existing unit tests (run `gradlew testDebugUnitTest`; will be checked by CI).
 - [ ] This contribution includes tests for any new functionality, and maintains tests for any updated functionality.
+- [ ] This contribution adheres to our [Engineering process](https://github.com/thunderbird/thunderbird-android/tree/main/docs/engineering) (RFC/Technical Design/ADR)
 - [ ] This PR has a descriptive title and body that accurately outlines all changes made, and contains a reference to any issues that it fixes (e.g. _Closes #XXX_ or _Fixes #XXX_).

AGENTS.md

@@ -23,7 +23,7 @@ The repository implements a white-label architecture producing:
 - `app-k9mail`: K-9 Mail
 
 Project documentation resides in the `docs/` directory.
-Architectural Decision Records (ADRs) are located in `docs/architecture/adr/`.
+Architectural Decision Records (ADRs) are located in `docs/engineering/adr/`.
 
 Agents MUST consult relevant documentation before making architectural or structural changes.
 
@@ -43,7 +43,7 @@ Before making changes, agents MUST:
 
 - Read `README.md`, `docs/CONTRIBUTING.md`, and relevant documentation in `docs/`
 - Review existing implementations in affected modules
-- Check for related ADRs in `docs/architecture/adr/`
+- Check for related ADRs in `docs/engineering/adr/`
 - Understand the module's role in the white-label architecture
 
 ### 3. Make Changes
@@ -78,7 +78,7 @@ Agents MUST:
 - Keep implementation details internal using the `internal` modifier
 - Bind implementations in `app-common` or app modules only
 
-New code MUST NOT violate the API/internal boundary, see [ADR-0009](docs/architecture/adr/0009-api-internal-split.md).
+New code MUST NOT violate the API/internal boundary, see [ADR-0009](docs/engineering/adr/0009-api-internal-split.md).
 
 If existing code violates this boundary, agents MUST NOT replicate the pattern and SHOULD move the code toward the
 intended architecture when modifying it.

README.md

@@ -64,15 +64,17 @@ We welcome contributions from everyone.
 - Thunderbird is supported solely by financial contributions from users like you. [Make a financial contribution today](https://www.thunderbird.net/donate/mobile/?form=tfa)!
 - Make sure to check out the [Mozilla Community Participation Guidelines](https://www.mozilla.org/about/governance/policies/participation/).
 
-### Architecture Decision Records (ADR)
+### Engineering Process
 
-We use [Architecture Decision Records](https://adr.github.io/) to document the architectural decisions made in the
-development of Thunderbird for Android. You can find them in the [`docs/architecture/adr`](docs/architecture/adr) directory.
+We use a structured engineering process to propose, decide, and deliver technical changes. This includes:
+- [Requests for Comments (RFCs)](docs/engineering/rfcs/README.md) for technical direction.
+- [Technical Designs](docs/engineering/technical-designs/README.md) for implementation details.
+- [Architecture Decision Records (ADRs)](docs/engineering/adr/README.md) for durable architectural decisions.
 
-For more information about our ADRs, please see the [ADRs README](docs/architecture/adr/README.md).
+You can find more information in the [`docs/engineering`](docs/engineering) directory.
 
-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.
+We encourage team members and contributors to read through our engineering documentation to understand the
+processes and decisions that have shaped this project so far.
 
 ## K-9 Mail
 

docs/CONTRIBUTING.md

@@ -41,6 +41,18 @@ We don’t track new ideas or feature requests in GitHub Issues.
 - Start a discussion in [Mozilla Connect – Ideas](https://connect.mozilla.org/t5/ideas/idb-p/ideas/label-name/thunderbird%20android)
 - Once a feature is accepted and work is planned, maintainers will create the corresponding GitHub issue(s).
 
+**GitHub Work:**
+
+GitHub Bug Issues track confirmed defects. GitHub Feature Issues and GitHub Task Issues track work that maintainers have
+accepted and planned. New feature proposals still start in Mozilla Connect; maintainers create GitHub issues after a
+proposal is accepted and scheduled.
+
+- External contributors should start from an existing GitHub Bug Issue, GitHub Feature Issue, or GitHub Task Issue.
+- Bug issues labeled `unconfirmed` are not ready for contributions.
+- Issues labeled `tb-team` are reserved for maintainers.
+- If you are unsure whether an existing issue is ready for your contribution, follow
+  [Working From GitHub Issues](contributing/contribution-workflow.md#working-from-github-issues).
+
 ## 🌐 Translations
 
 If you'd like to help to translate Thunderbird for Android, please visit:
@@ -60,6 +72,7 @@ development, testing, and review.
 
 ### 🏗️ Development Practices
 
+* **[Engineering](engineering/README.md)** – Process and artifacts for proposing, deciding, and delivering technical changes (RFCs, Technical Designs, ADRs).
 * **[Architecture](architecture/README.md)** – System design: module types, UI/Domain/Data layers, offline-first.
 * **[Development Guidelines](contributing/development-guide.md)** – Project-specific conventions and quick “do’s & don’ts.”
 * **[Code Quality Guide](contributing/code-quality-guide.md)** – Style rules, static analysis tools, and security practices.

docs/SUMMARY.md

@@ -29,18 +29,38 @@ generator, in this case, **mdbook**. It defines the structure and navigation of
   - [Settings](architecture/settings.md)
   - [Feature Flags](architecture/feature-flags.md)
   - [Legacy Module Integration](architecture/legacy-module-integration.md)
-  - [Architecture Decision Records](architecture/adr/README.md)
+- [Engineering](engineering/README.md)
+  - [Delivery Planning](engineering/delivery-planning.md)
+    - [Milestone Issues](engineering/milestone-issues/README.md)
+      - [Template](engineering/milestone-issues/0000-milestone-issue-template.md)
+  - [User Journeys](engineering/user-journeys/README.md)
+    - [Template](engineering/user-journeys/0000-user-journey-template.md)
+  - [RFCs](engineering/rfcs/README.md)
+    - [Template](engineering/rfcs/0000-rfc-template.md)
+    - [Proposed]()
+    - [Accepted]()
+    - [Rejected]()
+    - [Obsolete]()
+  - [Architecture Decision Records](engineering/adr/README.md)
+    - [Template](engineering/adr/0000-adr-template.md)
+    - [Proposed]()
     - [Accepted]()
-      - [0001 - Switch From Java to Kotlin](architecture/adr/0001-switch-from-java-to-kotlin.md)
-      - [0002 - UI - Wrap Material Components in Atomic Design System](architecture/adr/0002-ui-wrap-material-components-in-atomic-design-system.md)
-      - [0003 - Test - Switch Test Assertions From Truth to Assertk](architecture/adr/0003-switch-test-assertions-from-truth-to-assertk.md)
-      - [0004 - Naming Conventions for Interfaces and Their Implementations](architecture/adr/0004-naming-conventions-for-interfaces-and-their-implementations.md)
-      - [0005 - Central Project Configuration](architecture/adr/0005-central-project-configuration.md)
-      - [0006 - White Label Architecture](architecture/adr/0006-white-label-architecture.md)
-      - [0007 - Project Structure](architecture/adr/0007-project-structure.md)
-      - [0008 - Change Shared Module package to `net.thunderbird`](architecture/adr/0008-change-shared-modules-package-name.md)
+      - [0001 - Switch From Java to Kotlin](engineering/adr/0001-switch-from-java-to-kotlin.md)
+      - [0002 - UI - Wrap Material Components in Atomic Design System](engineering/adr/0002-ui-wrap-material-components-in-atomic-design-system.md)
+      - [0003 - Test - Switch Test Assertions From Truth to Assertk](engineering/adr/0003-switch-test-assertions-from-truth-to-assertk.md)
+      - [0004 - Naming Conventions for Interfaces and Their Implementations](engineering/adr/0004-naming-conventions-for-interfaces-and-their-implementations.md)
+      - [0005 - Central Project Configuration](engineering/adr/0005-central-project-configuration.md)
+      - [0006 - White Label Architecture](engineering/adr/0006-white-label-architecture.md)
+      - [0007 - Project Structure](engineering/adr/0007-project-structure.md)
+      - [0008 - Change Shared Module package to `net.thunderbird`](engineering/adr/0008-change-shared-modules-package-name.md)
+    - [Rejected]()
+    - [Obsolete]()
+  - [Technical Designs](engineering/technical-designs/README.md)
+    - [Template](engineering/technical-designs/0000-technical-design-template.md)
     - [Proposed]()
+    - [Accepted]()
     - [Rejected]()
+    - [Obsolete]()
 - [User Guide]()
   - [Setup]()
     - [Installing ADB](user-guide/setup/installing-adb.md)

docs/architecture/README.md

@@ -16,10 +16,20 @@ The application follows a modular architecture with clear separation between dif
 
 ## 📝 Architecture Decision Records
 
-The [Architecture Decision Records](adr/README.md) document the architectural decisions made during the development of the
+The [Architecture Decision Records](../engineering/adr/README.md) document the architectural decisions made during the development of the
 project, providing context and rationale for key technical choices. Reading through these decisions will improve your
 contributions and ensure long-term maintainability of the project.
 
+## 🏗️ Engineering Process
+
+We use a structured engineering process to propose, decide, and deliver technical changes. This includes:
+
+- **[RFCs](../engineering/rfcs/README.md)** for proposing technical direction and reaching consensus.
+- **[Technical Designs](../engineering/technical-designs/README.md)** for detailing implementation plans.
+- **[ADRs](../engineering/adr/README.md)** for recording durable architectural decisions.
+
+For more details on how these artifacts work together, see the [Engineering](../engineering/README.md) documentation.
+
 ## 📦 Module Structure
 
 The application is organized into several module types:

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

@@ -16,7 +16,7 @@ Paste this into your PR to self-check:
 - [ ] Security/privacy: inputs validated; no PII in logs; TLS; secure storage; permission changes documented
 - [ ] i18n: No new localizable strings unless justified; translations policy followed
 - [ ] Release train: feature flags set; uplift label + risk/impact (if applicable)
-- [ ] Docs/CHANGELOG updated; issues linked (Fixes #123); PR title/commits clear
+- [ ] Docs/CHANGELOG updated; issues linked (Fixes #123); Engineering process (RFC/TechDesign) followed; PR title/commits clear
 ```
 
 ## 🧑‍💻 For Code Authors (self‑review checklist)
@@ -35,7 +35,7 @@ Paste this into your PR to self-check:
 3. **Architecture & module boundaries**
    - Follow modular rules: API vs internal separation; use `internal` visibility for all code in `:internal` modules (except for DI).
    - Only depend on `:feature:foo:api` externally; `:feature:foo:internal` (and legacy `:feature:foo:impl`) are internal.
-     See [ADR-0009](../architecture/adr/0009-api-internal-split.md) for full module structure and dependency rules.
+     See [ADR-0009](../engineering/adr/0009-api-internal-split.md) for full module structure and dependency rules.
    - Respect MVI/Compose patterns in the UI layer; keep business logic out of UI implementation.
    - Prefer constructor injection with Koin; keep constructors simple and dependencies explicit.
 4. **Code quality & style**
@@ -63,6 +63,7 @@ Paste this into your PR to self-check:
 10. **Documentation & metadata**
     - Update relevant docs, CHANGELOG entries and add context as needed.
     - Link relevant issues using GitHub keywords so they auto-close on merge (`Fixes #123`, `Resolves #456`).
+    - Adhere to the [Engineering process](../engineering/README.md) (RFC/Technical Design/ADR) if applicable.
     - For commit format, see the [Git Commit Guide](git-commit-guide.md)
 11. **CI status**
     - Ensure CI is green
@@ -72,8 +73,9 @@ Paste this into your PR to self-check:
 
 1. **Correctness & requirements**
    - Does the change solve the stated problem? Any edge cases missed? Are invariants upheld?
+   - If non-trivial, does it align with the agreed [RFC or Technical Design](../engineering/README.md)?
 2. **Architecture & boundaries**
-   - Adheres to module API/internal separation per [ADR-0009](../architecture/adr/0009-api-internal-split.md) and project architecture (UI: Compose/MVI, Domain, Data).
+   - Adheres to module API/internal separation per [ADR-0009](../engineering/adr/0009-api-internal-split.md) and project architecture (UI: Compose/MVI, Domain, Data).
    - No cross‑module leaks (check for proper `internal` visibility in `:internal` modules); dependencies flow in the right direction.
    - Note: The codebase still contains `:impl` modules during ADR-0009 migration; treat them with the same separation rules as `:internal`.
 3. **Readability & maintainability**