Skip to content

Commit 4fb1e45

Browse files
wmontwewmontwe
committed
docs: add development environment instructions
1 parent 4db8243 commit 4fb1e45

File tree

2 files changed

+187
-0
lines changed

2 files changed

+187
-0
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ generator, in this case, **mdbook**. It defines the structure and navigation of
66
---
77

88
- [Contributing](CONTRIBUTING.md)
9+
- [Development Environment](contributing/development-environment.md)
910
- [Code Quality Guide](contributing/code-quality-guide.md)
1011
- [Code Review Guide](contributing/code-review-guide.md)
1112
- [Git Commit Guide](contributing/git-commit-guide.md)

‎docs/contributing/development-environment.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# 🚀 Development Environment
2+
3+
This guide will help you set up your development environment and get started with contributing to the Thunderbird for
4+
Android project.
5+
6+
## 📋 Prerequisites
7+
8+
Before you begin, ensure you have the following installed:
9+
10+
- **[Java Development Kit (JDK)](https://adoptium.net/temurin/releases/?version=17)** - Version 17 or higher (Temurin OpenJDK recommended)
11+
- **[Android Studio](https://developer.android.com/studio)** - Latest stable version recommended
12+
- **[Git](https://git-scm.com/downloads)** - For version control
13+
- **Gradle** - Use the Gradle wrapper included in this repo (`./gradlew`); no separate install required
14+
- **Android SDK & command-line tools** – Installed and managed via Android Studio SDK Manager
15+
16+
Recommended knowledge (helpful, not strictly required):
17+
18+
- **[Kotlin](https://kotlinlang.org/docs/home.html)** - Primary programming language for the project
19+
- **[Jetpack Compose](https://developer.android.com/jetpack/compose)** - UI toolkit used for Android
20+
- **[Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)** - Shared code across modules where applicable
21+
- **[Android Development](https://developer.android.com/guide)** - Basic understanding of Android app development
22+
- **[GitHub](https://docs.github.com/en)** - For managing contributions and pull requests
23+
24+
## 🔧 Setting Up the Development Environment
25+
26+
### 1. Fork the Repository
27+
28+
All contributions must be made from a fork.
29+
30+
1. Go to the [Thunderbird for Android repository](https://github.com/thunderbird/thunderbird-android)
31+
2. Click the **Fork** button in the top-right corner
32+
3. Create a fork under your GitHub account
33+
34+
### 2. Clone Your Fork
35+
36+
After forking the repository, clone your fork to your local machine:
37+
38+
```bash
39+
git clone https://github.com/YOUR-USERNAME/thunderbird-android.git
40+
cd thunderbird-android
41+
```
42+
43+
Replace `YOUR-USERNAME` with your GitHub username.
44+
45+
### 3. Import the Project into Android Studio
46+
47+
1. Open Android Studio
48+
2. Select **Open an Existing Project**
49+
3. Navigate to the cloned repository and open it
50+
4. Wait for project sync and indexing
51+
52+
### 4. Configure Android Studio
53+
54+
For the best development experience, we recommend the following settings:
55+
56+
- **Recommended plugins:**
57+
- **Kotlin Multiplatform** (usually bundled; if not, install from the JetBrains Marketplace)
58+
59+
## 🏗️ Building the Project
60+
61+
### Building from Android Studio
62+
63+
1. Select the app module (e.g., `app-thunderbird` or `app-k9mail`) in the **Run/Debug Configuration** dropdown
64+
2. Select build variant you want to work with (Debug/Release) from Build Variants window
65+
3. Click the **Build** button or press `Ctrl+F9` (Windows/Linux) or `Cmd+F9` (macOS)
66+
67+
### Building from Command Line
68+
69+
A Gradle wrapper is included in the project, so you can build the project from the command line without installing
70+
Gradle globally. Run the following commands from the root of the project, where `./gradlew` is the Gradle wrapper script
71+
and the command to `build` runs tests and other checks, while `assemble` only compiles the code and packages the APK.
72+
73+
```bash
74+
# Build all variants
75+
./gradlew assemble
76+
./gradlew build
77+
78+
# Build debug or release variant
79+
./gradlew assembleDebug
80+
./gradlew assembleRelease
81+
82+
# Build a specific app module
83+
./gradlew :app-thunderbird:assembleDebug
84+
./gradlew :app-k9mail:assembleDebug
85+
86+
# Build a specific library/feature module
87+
./gradlew :module-name:build
88+
```
89+
90+
Replace `module-name` with the actual name of the module you want to build.
91+
92+
## 🚀 Running the Application
93+
94+
### Running on an Emulator
95+
96+
1. [Set up an Android Virtual Device (AVD)](https://developer.android.com/studio/run/managing-avds) in Android Studio with a recent API level with Google APIs image.
97+
2. Select the AVD from the device dropdown.
98+
3. Click the **Run** button or press `Shift+F10` (Windows/Linux) or `Ctrl+R` (macOS)
99+
100+
### Running on a Physical Device
101+
102+
1. [Enable Developer Options and USB Debugging](https://developer.android.com/studio/debug/dev-options) on your device
103+
2. Connect your device to your computer vis USB and confirm trust dialog if prompted
104+
3. Select your device from the device dropdown and click **Run**
105+
106+
## 🧪 Running Tests
107+
108+
```bash
109+
# Run all tests across modules
110+
./gradlew test
111+
112+
# Run unit tests for a specific module
113+
./gradlew :module-name:test
114+
115+
# Run instrumented tests (device/emulator required)
116+
./gradlew connectedAndroidTest
117+
```
118+
119+
See the [Testing Guide](testing-guide.md) for details.
120+
121+
## 🔍 Checking Code Quality
122+
123+
Maintaining high code quality is essential for the long-term sustainability of the Thunderbird for Android project. The project uses several tools and practices to ensure code quality:
124+
125+
- **Static Analysis Tools**: Android Lint, Detekt, and Spotless
126+
- **Code Style Guidelines**: Kotlin style guide and project-specific conventions
127+
- **Testing**: Unit tests, integration tests, and UI tests
128+
- **Code Reviews**: Peer review process for all code changes
129+
- **Continuous Integration**: Automated checks for build success, tests, and code quality
130+
131+
To run the basic code quality checks:
132+
133+
```bash
134+
# Run lint checks
135+
./gradlew lint
136+
137+
# Run detekt
138+
./gradlew detekt
139+
140+
# Check code formatting
141+
./gradlew spotlessCheck
142+
143+
# Apply code formatting fixes
144+
./gradlew spotlessApply
145+
```
146+
147+
See the [Code Quality Guide](code-quality-guide.md) for more details.
148+
149+
## 🐛 Debugging
150+
151+
### Using the Debugger
152+
153+
1. Set breakpoints in your code by clicking in the gutter next to the line numbers
154+
2. Start debugging by clicking the **Debug** button or pressing `Shift+F9` (Windows/Linux) or `Ctrl+D` (macOS)
155+
3. Use the debugger controls to step through code, inspect variables, and evaluate expressions
156+
4.
157+
158+
See the [Android Studio Debugger Guide](https://developer.android.com/studio/debug) for a detailed description.
159+
160+
### Logging
161+
162+
Use the project's core logging API `net.thunderbird.core.logging.Logger`, which is provided via dependency injection
163+
(Koin). Avoid logging **personally identifiable information (PII)**.
164+
165+
Example with DI (Koin):
166+
167+
```kotlin
168+
class ExampleActivity : ComponentActivity() {
169+
private val logger: Logger by inject()
170+
171+
fun doSomething() {
172+
logger.debug(tag = "Example") { "Debug message" }
173+
val exception = RuntimeException("Something went wrong")
174+
logger.error(tag = "Example", throwable = exception) { "Error message" }
175+
}
176+
}
177+
```
178+
179+
### Profiling
180+
181+
Use Android Studio's built-in [Android Profiler](https://developer.android.com/studio/profile/android-profiler) to monitor:
182+
- CPU usage
183+
- Memory allocation
184+
- Network activity
185+
186+
For performance-sensitive code, also consider Baseline Profiles or Macrobenchmark tests.

0 commit comments

Comments
 (0)