|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This repository is the official Wikipedia app for Android, with features for reading Wikipedia articles, exploring the Wikipedia ecosystem by searching and browsing related content, as well as editing and administering Wikipedia content. |
| 4 | + |
| 5 | +## General architecture |
| 6 | + |
| 7 | +- The `app` directory contains all the code for the app itself. |
| 8 | +- The `analytics/testkitchen` directory is a work-in-progress analytics engine that will eventually integrate with the app, but not yet. |
| 9 | + |
| 10 | +### Build flavors |
| 11 | + |
| 12 | +- The `dev` flavor is used for day-to-day development and running on local devices by developers. |
| 13 | +- The `alpha` flavor is used for continuous integration and QA testing, both manually and using GitHub Actions. |
| 14 | +- The `beta` flavor is for building and deploying to the [Wikipedia Beta](https://play.google.com/store/apps/details?id=org.wikipedia.beta) app on the Play Store. |
| 15 | +- The `prod` flavor is for building and deploying to the production [Wikipedia](https://play.google.com/store/apps/details?id=org.wikipedia) app on the Play Store and other third-party app stores. |
| 16 | +- The `fdroid` flavor is for building and deploying to the [F-Droid store](https://f-droid.org/en/packages/org.wikipedia) specifically. This flavor is configured to exclude any closed-source packages or libraries. All such code is contained in the `src/extra` directory, which is included in all other flavors, but is stubbed out in the `fdroid` flavor. |
| 17 | + |
| 18 | +### Project organization |
| 19 | + |
| 20 | +Classes and packages are organized roughly by "feature": |
| 21 | +``` |
| 22 | +/app/src/main/java/org/wikipedia/ |
| 23 | +├── dataclient/ # Model classes and service layer for MediaWiki and Wikipedia APIs |
| 24 | +├── analytics/ # Model classes and service logic for our current analytics engine (Event Platform) |
| 25 | +├── feed/ # Fragments and Views related to the Exlore Feed |
| 26 | +├── talk/ # Activities and Views related to Wikipedia Talk pages |
| 27 | +├── page/ # Activities and Views for browsing Wikipedia articles in a WebView |
| 28 | +├── edit/ # Activities and Views for editing Wikipedia articles |
| 29 | +``` |
| 30 | +...and so on. |
| 31 | + |
| 32 | +### Libraries and dependencies |
| 33 | + |
| 34 | +- Jetpack Compose for any new features. View Bindings for legacy features. |
| 35 | + - Since the app offers four different color themes, always wrap Compose screens in the `BaseTheme` component which handles our custom themes. |
| 36 | + - Whenever possible, translate a legacy feature to Jetpack Compose before adding new functionality. |
| 37 | +- Retrofit for network calls, with occasional direct usages of OkHttp. |
| 38 | +- Kotlinx.serialization for serializing and deserializing JSON objects from remote APIs and local storage. |
| 39 | +- Coil for loading images. |
| 40 | +- Room for database management. |
| 41 | +- JUnit and Robolectric for unit tests. |
| 42 | +- Espresso for instrumented tests. |
| 43 | + |
| 44 | +### Miscellaneous |
| 45 | + |
| 46 | +- SharedPreferences are encapsulated in `Prefs.kt`. If adding a new preference, follow the pattern in that file. |
| 47 | +- When setting up an A/B test for any feature, subclass from `ABTest.kt`, which automatically assigns the current user into a test bucket. |
| 48 | + |
| 49 | +## Code conventions |
| 50 | + |
| 51 | +- To check if the app builds without errors: `./gradlew assembleDevDebug` |
| 52 | + - Do NOT run other static analysis tools (ktlint, checkstyle, lint) during development. This should only be done as a final step, when ready to submit a pull request. |
| 53 | +- ALWAYS prefer Jetpack Compose for new UI features, with a corresponding backing ViewModel class that handles state. |
| 54 | + - Whenever possible, use the components and extensions found in the `compose/` directory. |
| 55 | + - Important: for Text composables that might display HTML text from spannable CharSequence strings (bold, italic, etc), use our `compose/components/HtmlText` composable instead of the standard Text() composable. |
| 56 | + - For new Composable, create at least one `Preview` function that showcases the corresponding composable. |
| 57 | +- ALWAYS prefer self-documenting names of variables, functions, and fields. Don't write redundant comments that explain what the next line does. |
| 58 | +- Avoid using deprecated APIs and classes in new code whenever possible. |
| 59 | +- Avoid using reflection, unless all other options are exhausted. |
| 60 | + |
| 61 | +## Release notes |
| 62 | + |
| 63 | +- Every previous release is denoted by a git tag of the form `r/...`. Release notes must be composed based on git commits that happened after the last release tag. |
| 64 | +- To get the hash of the last release tag: git show-ref -s <last-release-tag> |
| 65 | +- To get a list of commits since last release: git log <last-release-hash>..HEAD --oneline --no-merges |
| 66 | +- Do NOT include dependency updates, localization updates, or static data updates. |
| 67 | +- Release notes should be terse, but understandable by a general audience. |
| 68 | +- Release notes must be a single paragraph of natural, friendly text. It should NOT be a list of bullet points. |
0 commit comments