CONTRIBUTING.md

Contributing to Jerboa

• Contributing to Jerboa
  • Ways to contribute
  • Application structure
  • Code contributions
    • Kotlin
    • Code quality
  • Adding translations
  • Theming guide
  • Updating the instance list
  • Generate compose compiler metrics
  • Testing migrations
  • Updating the Baseline profiles

Ways to contribute

• Participate here and start answering questions.
• File GitHub issues for bug reports from /c/Jerboa. Watch the project for duplicate reports and link them to the first report so devs can easily close dupes.
• File new bug reports for issues you find.
• Add missing translations
• Code contributions

Application structure

• Basic Modern Android Development tech stack (Compose, Navigation, Coroutines, AndroidX)
• Guide to App Architecture, without domain layer. Basically, MVVM + Repositories for data access.
• Manual DI

Code contributions

You can open Jerboa in AndroidStudio, version 2022.3.1 or later (Giraffe).

Use Java 11+, preferably Java 17

Kotlin

This project is full Kotlin. Please do not write Java classes.

Code quality

The code must be formatted to a common standard.

To check for violations

./gradlew lintKotlin

Or just run this to fix them

./gradlew formatKotlin

Markdown and yaml files are formatted according to prettier.

You can install prettier either through the plugin, or globally using npm npm install -g prettier

To check for violations

prettier -c "*.md" "*.yml"

To fix the violations

prettier --write "*.md" "*.yml"

Adding translations

You can find the translations in the app/src/main/res/values-{locale}/strings.xml file. You can open it in android studio, right click and click open translations editor or you can directly edit the files.

If you add a new locale. Also add it in locales_config.xml. Don't forget to escape ' in translations.

Theming guide

To add a custom theme:

• Use google's Material 3 custom theme generator, and save your Theme.kt file.
• Copy the theme into Color.kt like the others.
• Add the theme to the ThemeColor enum in Types.kt
• Add a translation string in strings.xml for your theme name.
• Add the theme to the colorPairs in Theme.kt

Updating the instance list

There is a custom gradle task that generates all the lemmy instances that this app directly supports. It updates the lemmy instances list in DefaultInstances.kt and the AndroidManifest. It uses the fediverse api and filters on the monthly users. You can run it by doing

 ./gradlew app:updateInstances

Generate compose compiler metrics

You can generate the compose compiler metrics by executing the following gradle task.

./gradlew assembleRelease --rerun-tasks -P enableComposeCompilerReports=true

Then you will find the metrics in app/build/compose_metrics directory. See this link for more information on these metrics

Testing migrations

If you add a migration to the DB, test it with this gradle task

./gradlew app:connectAndroidTest

Updating the Baseline profiles

You can generate the latest baseline profiles by executing the following gradle task. It will generate the baseline profiles and the startup profiles.

The baseline profile code is located in the Benchmarks module.

Be warned that this task will take a long time to run (+30m) and can fail.

The variant for app needs to be set to benchmarkRelease. There should be no device connected and it should start an emulator with the correct settings.

./gradlew :app:generateBaselineProfile

see https://developer.android.com/topic/performance/baselineprofiles/overview