Skip to content

Home

# Android Library Template

This is a template for creating Android Open Source libraries. This template features

  • 🏗️Basis Project structure that includes demo and library modules
  • 🚀 CI/CD with GitHub Actions for release and snapshot builds, documentation generation
  • 🔍 Code Quality checks with Detekt, Spotless and Tests
  • 📕 Documentation setup with Dokka and MkDocs
  • 📦 Dependency management with Version Catalogue
  • 📝 CHANGELOG following a keepchangelog.com format and JetBrains Changelog Plugin to accompany the release notes
  • 🔧 Gradle Convention Plugins for consistent build configuration across modules
  • 🌐 GH pages to host the documentation

Table of Contents

Usage

  1. Click on the Use this template button to create a new repository from this template.
  2. Update the gradle.properties files with the correct values for your library.
  3. Add following secrets to your repository to enable publishing to Maven Central (For more information about following properties, please refer to Gradle Maven Publish Plugin)
  4. SIGNING_PASSWORD - Password for the GPG key
  5. SIGNING_PRIVATE_KEY - GPG key
  6. SONATYPE_NEXUS_USERNAME - Sonatype username
  7. SONATYPE_NEXUS_PASSWORD - Sonatype password

Branching Strategy

This templates follows a trunk-based approach using its main branch as the single source of truth for all changes. Feature/Fixes and etc branches are created from main and are merged back using pull requests.

CI/CD

This template uses GitHub Actions for CI/CD. The following workflows are set up:

  • Verify Pull Request: Checks code quality with Detekt and Spotless, and runs tests
  • Publish Snapshot: Publishes a snapshot version of the library to GitHub Packages
  • Publish Release: Publishes a release version of the library to GitHub Packages
  • Generate Docs: Generates documentation with Dokka and MkDocs

Release Management

The release management is tied to the GitHub Releases.

Draft Releases & Snapshots

Every push to the main triggers main workflow that will create a draft release. The draft release version is set to the current version located in gradle.properties and the release notes for it are taken from the CHANGELOG.md.

In case the Draft Release exists already, it will be deleted and replaced with new one, so that there is only one draft release.

Together with Draft Releases the snapshot is published This is done by applying -SNAPSHOT suffix to the version and publishing it to the Maven Central.

Release

By promoting a Draft Release, the release workflow is triggered. It will publish the library to the to the Maven Central.

Changelog

This template follows the Keep a Changelog format for changelog entries. The changelog is stored in the CHANGELOG.md file. When Draft Release is created, the Changelog plugin from Jetbrains to update the release notes with the latest changes according to the latest version specified in the gradle.properties file.

Documentation

This template uses Dokka for code documentation and MkDocs Material for project documentation. For more information on how to use MkDocs, please refer to the MkDocs documentation and Mkdocs Material documentation.

The Dokka plugin is applied to the library module and generates KDocks documentation for the library. The generated documentation is published together with the project documentation and can be accessed using github pages.

Github Pages

Every push to the main branch triggers the Generate Docs workflow that will generate the documentation and publish it to the gh-pages branch. The documentation can be accessed using the following link: https://<username>.github.io/<repository-name>/

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.

Resources