cortinico / kotlin-android-template

Android + Kotlin + Github Actions + ktlint + Detekt + Gradle Kotlin DSL + buildSrc = ❤️

kotlin-android-template 🤖

A simple Github template that lets you create an Android/Kotlin project and be up and running in a few seconds.

This template is focused on delivering a project with static analysis and continuous integration already in place.

How to use 👣

Just click on button to create a new repo starting from this template.

Once created don't forget to update the:

• App ID
• AndroidManifest (here and here)
• Package of the source files

Features 🎨

• 100% Kotlin-only template.
• 4 Sample modules (Android app, Android library, Kotlin library, Jetpack Compose Activity).
• Jetpack Compose setup ready to use.
• Sample Espresso, Instrumentation & JUnit tests.
• 100% Gradle Kotlin DSL setup.
• CI Setup with GitHub Actions.
• Publish to Maven Central with Github Actions.
• Dependency versions managed via buildSrc.
• Kotlin Static Analysis via detekt and ktlint.
• Issues Template (bug report + feature request).
• Pull Request Template.

Troubleshooting

For help with issues which you might encounter when using this template, please refer to TROUBLESHOOTING.md

Gradle Setup 🐘

This template is using Gradle Kotlin DSL as well as the Plugin DSL to setup the build.

Dependencies are centralized inside the Gradle Version Catalog in the libs.versions.toml file in the gradle folder.

Static Analysis 🔍

This template is using detekt to analyze the source code, with the configuration that is stored in the detekt.yml file (the file has been generated with the detektGenerateConfig task). It also uses the detekt-formatting plugin which includes the ktlint rules (see https://detekt.dev/docs/rules/formatting/).

CI ⚙️

This template is using GitHub Actions as CI. You don't need to setup any external service and you should have a running CI once you start using this template, just make sure that you turn on the "Read and Write permissions" on the Action Settings of your repository.

There are currently the following workflows available:

• Validate Gradle Wrapper - Will check that the gradle wrapper has a valid checksum
• Pre Merge Checks - Will run the build, check and publishToMavenLocal tasks.
• Publish Snapshot - Will publish a -SNAPSHOT of the libraries to Sonatype.
• Publish Release - Will publish a new release version of the libraries to Maven Central on tag pushes.

Publishing 🚀

The template is setup to be ready to publish a library/artifact on a Maven Repository.

For every module you want to publish you simply have to add the publish plugin:

plugins {
    publish
}

To Maven Central

In order to use this template to publish on Maven Central, you need to configure some secrets on your repository:

Secret name	Value
ORG_GRADLE_PROJECT_NEXUS_USERNAME	The username you use to access Sonatype's services (such as Nexus and Jira)
ORG_GRADLE_PROJECT_NEXUS_PASSWORD	The password you use to access Sonatype's services (such as Nexus and Jira)
ORG_GRADLE_PROJECT_SIGNING_KEY	The GPG Private key to sign your artifacts. You can obtain it with gpg --armor --export-secret-keys <[email protected]> or you can create one key online on pgpkeygen.com. The key starts with a -----BEGIN PGP PRIVATE KEY BLOCK-----.
ORG_GRADLE_PROJECT_SIGNING_PWD	The passphrase to unlock your private key (you picked it when creating the key).

The template already attaches -sources.jar to your publications via the new AGP publishing DSL.

Once set up, the following workflows will take care of publishing:

• Publish Snapshot - To publish -SNAPSHOT versions to Sonatype. The workflow is setup to run either manually (with workflow_dispatch) or on every merge.
• Publish Release - Will publish a new release version of the libraries to Maven Central on tag pushes. You can trigger the workflow also manually if needed.

To Jitpack

If you're using JitPack, you don't need any further configuration and you can just configure the repo on JitPack.

You probably want to disable the [Publish Snapshot] and Publish Release workflows (delete the files), as Jitpack will take care of that for you.

Project Structure

The project includes three sub-projects, each in their own subdirectories:

• app: The source for the final Android application.
• library-android: The source for an Android library including UI.
• library-kotlin: The source for a UI-less Kotlin library.
• library-compose: The source for a UI library with Jetpack Compose library.

The following additional top-level directories configure & support building the app & projects:

• buildSrc: Contains shared Gradle logic as precompiled script plugins
• config: Contains the Detekt configuration file.
• gradle: Contains Gradle Configuration files such as the Gradle Version Catalog and the Gradle Wrapper.

Finally, the following hidden top-level directories provide functionality for specific development systems:

• .github: Defines the Github Actions CI tasks and templates for new pull requests, issues, etc.
• .idea: Sets common initial project settings when the project is opened in Android Studio or IntelliJ IDEA.

Contributing 🤝

Feel free to open a issue or submit a pull request for any bugs/improvements.

kotlin-android-template's Issues

Rename master branch to main

It would be nice to change the name of the initial branch from master to main.

Suggestion for Danger Integration

⚠️ Is your feature request related to a problem? Please describe

I have just seen this repo and thought auto pr review bot could help developers productivity

💡 Describe the solution you'd like

as static analysis tools already integrated we could integrate danger to use static analysis tools output as a pr review.

🤚 Do you want to develop this feature yourself?

• Yes
• No

The Dependencies.kt mentioned in the README does not exist

The Dependencies.kt mentioned in the README does not exist.

Dependencies are centralized inside the Dependencies.kt file in the buildSrc folder. This provides convenient auto-completion when writing your gradle files.

Implementing a more comprehensive .gitignore

⚠️ Is your feature request related to a problem? Please describe

When getting started with the template and the first build new directories that are typically ignored for version control are not successfully ignored. (eg. various .xml files that relate to IDE config)

💡 Describe the solution you'd like

A more comprehensive .gitignore could be used such as this one could be beneficial to this template as it is one less thing to worry about.

🤚 Do you want to develop this feature yourself?

• Yes
• No

Should use Compose BOM instead of reference to specific compose version

⚠️ Is your feature request related to a problem? Please describe

Nowdays it's recommended to use compose BOM versioning instead of hard references to using a specific version for all compose libraries. See https://developer.android.com/jetpack/compose/bom

💡 Describe the solution you'd like

A solution with version catalogs is explained at https://developer.android.com/jetpack/compose/bom#does_the_bom_work_with_version_catalogs. At work I am not using version catalogs yet so I can't get it working with a <2min PR 😢

🤚 Do you want to develop this feature yourself?

• Yes
• No (Note: At least not right now)

Where should I add e.g. Hilt Android and AndroidX Navigation Safe Args Gradle Plugins?

Should I add them inside buildSrc folder?

plugins {
    `kotlin-dsl`
}

repositories {
    google()
    mavenCentral()
}

dependencies {
    implementation(group = "com.android.tools.build", name = "gradle", version = "7.0.1")
    implementation(kotlin(module = "gradle-plugin", version = "1.5.30"))
    implementation(group = "com.google.dagger", name = "hilt-android-gradle-plugin", version = "2.38.1")
    implementation(group = "androidx.navigation", name = "navigation-safe-args-gradle-plugin", version = "2.3.5")
}

Thanks

Add a flavor for Compose

⚠️ Is your feature request related to a problem? Please describe

One of the use cases of this repo is to build sample projects for submitting bug reports. This has been a painpoint since my development directory is full of different sample projects, and often I need to upgrade to the latest version of the tools I used.

💡 Describe the solution you'd like

Add a flavor for using Jetpack Compose. As Compose still evolves rapidly, and I have been struggling a lot to keep a repo up-to-date with all the build setup.
The flavor could be a subproject or a different branch: I am open to any suggestion.

🤚 Do you want to develop this feature yourself?

• Yes
• No

Replace ActivityTestRule with activityScenarioRule

⚠️ Is your feature request related to a problem? Please describe

ActivityTestRule inside the espresso test case is deprecated .

💡 Describe the solution you'd like

I believe we could add JUnit KTX extension library , and then:

@get:Rule val activityScenarioRule = activityScenarioRule<MainActivity>()

🤚 Do you want to develop this feature yourself?

• Yes
• No

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency androidx.test:runner to v1.5.2
• Update gradle/wrapper-validation-action action to v3

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• Update dependency org.jetbrains.kotlin:kotlin-gradle-plugin to v1.9.23

Detected dependencies

github-actions

.github/workflows/cleanup.yaml

• actions/checkout v4
• actions/setup-java v4
• gradle/gradle-build-action v2
• ad-m/github-push-action v0.8.0

.github/workflows/gradle-wrapper-validation.yml

• actions/checkout v4
• gradle/wrapper-validation-action v2

.github/workflows/pre-merge.yaml

• actions/checkout v4
• actions/setup-java v4
• gradle/gradle-build-action v2

.github/workflows/publish-release.yaml

• actions/checkout v4
• actions/setup-java v4
• gradle/gradle-build-action v2
• actions/upload-artifact v4

.github/workflows/publish-snapshot.yaml

• actions/checkout v4
• actions/setup-java v4
• gradle/gradle-build-action v2
• actions/upload-artifact v4

gradle

buildSrc/src/main/java/Coordinates.kt

buildSrc/src/main/java/Extensions.kt

gradle.properties

settings.gradle.kts

build.gradle.kts

app/build.gradle.kts

buildSrc/settings.gradle.kts

buildSrc/build.gradle.kts

buildSrc/src/main/kotlin/cleanup.gradle.kts

buildSrc/src/main/kotlin/publish.gradle.kts

gradle/libs.versions.toml

• junit:junit 4.13.2
• androidx.activity:activity-compose 1.9.0
• androidx.appcompat:appcompat 1.6.1
• androidx.constraintlayout:constraintlayout 2.1.4
• androidx.core:core-ktx 1.13.0
• androidx.test:rules 1.5.0
• androidx.test:runner 1.5.0
• androidx.test.ext:junit 1.1.5
• androidx.test.ext:junit-ktx 1.1.5
• androidx.compose:compose-bom 2024.04.01
• io.gitlab.arturbosch.detekt:detekt-formatting 1.23.6
• androidx.test.espresso:espresso-core 3.5.1
• com.android.tools.build:gradle 8.3.2
• org.jetbrains.kotlin:kotlin-gradle-plugin 1.9.20
• io.gitlab.arturbosch.detekt 1.23.6
• com.github.ben-manes.versions 0.51.0

library-android/build.gradle.kts

library-compose/build.gradle.kts

library-kotlin/build.gradle.kts

gradle-wrapper

gradle/wrapper/gradle-wrapper.properties

• gradle 8.7

---

• Check this box to trigger a request for Renovate to run again on this repository

Device Debugger

🐛 Describe the bug

⚠️ Current behavior

✅ Expected behavior

💣 Steps to reproduce

📷 Screenshots

📱 Tech info

• Device:
• OS:
• Library/App version:

Automatic replacement of AppId/package with Github Actions

I just bumped into the Jetbrains template for IntelliJ plugins (https://github.com/JetBrains/intellij-platform-plugin-template#getting-started). They have a Github Action that replaces the template values with values from the fork repo. I think it'd be a great addition to this template: it'll make sure users don't forget to remove the default value and save some manual configuration.

I'm not sure I'll have a lot of time to work on this but if someone feels like investigating Github Actions, I think that'd be a good fit.

Fix detekt link in the README

🐛 Describe the bug

Clicking the detekt link in the README opens https://github.com/arturbosch/detekt.

✅ Expected behavior

Clicking the detekt link in the README should open https://github.com/detekt/detekt because detekt has been moved from https://github.com/arturbosch/detekt

Need example of flavor in build.gradle.kts

⚠️ Is your feature request related to a problem? Please describe

In real project, we often have build flavor.

💡 Describe the solution you'd like

Add example of flavor staging and production in build.gradle.kts

🤚 Do you want to develop this feature yourself?

• Yes
• No
  (Sorry, I'm not so familiar with Kotlin Gradle script).

🐛 App Crash observed on factorial computation

🐛 Describe the bug

The Template App gets crashed when we click on compute button w/o entering any number in the EditText.

⚠️ Current behaviour

The Template App gets crashed when we click on compute button w/o entering any number in the EditText.

✅ Expected behaviour

The app should not get crashed.

💣 Steps to reproduce

1. Run the App.
2. Don't Enter any text in EditText.
3. Click compute button.
4. App gets crashed.

📷 Screenshots

📱 Tech info

• Device: Google Pixel 3
• OS: 10.0.0
• Library/App version: 1.0.0

Setup test coverage with jacoco/codecov

⚠️ Is your feature request related to a problem? Please describe

Add support for code coverage

💡 Describe the solution you'd like

Ideally we could setup jacoco + codecov to have an automated test report after every push/pr.

🤚 Do you want to develop this feature yourself?

• Yes
• No

This feature is up for grab

Add short directory descriptions to the readme

⚠️ Is your feature request related to a problem? Please describe

No clue why there are so many directories and what they do.

💡 Describe the solution you'd like

Add directory descriptions to readme or docs.

🤚 Do you want to develop this feature yourself?

• Yes
• No