How to improve your Android Library

If you are developing an android library (open source or not), it’s a good idea to follow some guidelines to guarantee high quality and also simplify your users and collaborators life’s. Here are some examples of best practices I recommended and also, tips you can follow.

1. Resources Prefixes

If any of your users override an android resource of your library by mistake, it can be very dangerous. For example, they could create a string resource with the same name you defined inside your library.

One way to avoid this (or at least reduce the chances of a name conflict) is to assign a prefix to all your library resources.

The prefix could be for example your library name or package name. You should add it to all the files inside the following directories

  • res/drawable
  • res/layout
  • res/menu
  • res/xml
  • res/raw

Additionally, prepend the prefix to the name of these resource types

  • string
  • plurals
  • color
  • dimen
  • declare-styleable
  • style
  • bool

You can also declare your library’s prefix on your build.gradle to let Android Studio know about it.

android {
resourcePrefix 'YOUR_PREFIX_'
Android Studio Extract Resource dialog autocompletes your prefix

2. Debug and release classifiers

If you have debug code or development utilities on your library, don’t include them on your release artifact (.aar). You could use classifiers to generate two different artifacts of your library according to your build types:

  • the debug artifact should include all your productive library code, plus any debugging code or utilities to be used by your users during the development.
  • the release artifact should only include the code of your library that will be included in the production APK.

To publish all your library variants you should add the following configuration to the build.gradle of your library

android {
publishNonDefault true

Then allocate your code on the debug, main or release directories according to your needs and when you upload your library you will have two artifacts

  • ARTIFACT_ID-VERSION-release.aar

Your library users should include your dependencies according to their needs. For example

debugCompile('GROUP_ID:ARTIFACT_ID:VERSION:debug@aar') {
transitive = true;
releaseCompile('GROUP_ID:ARTIFACT_ID:VERSION:release@aar') {
transitive = true;

3. Define a versioning scheme

Your users deserve to know which kind of changes are included on a release with just a quick look at your version number.

Are you breaking compatibility? Is it just a patch version? Following the semantic versioning guidelines is a good idea for your library versioning.

Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

I suggest you pick a versioning scheme and document it on your wiki.

4. Public available release notes

Your users will need to know all the details of each release you publish, including new features, improvements, resolved bugs, deprecated code and migration steps.

One way to resolve this is by having a changelog.

A change log is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

The site defines some useful conventions about writing good changelogs.

If you use GitHub Issues as issue tracker, you can take a look at this changelog generator that automates the process of keeping that file always updated.

I also recommend you use Github Releases and include your changelog as part of the description of each release you create. For example, you can take a look at

5. Publish to the Maven Central / Jcenter repositories

If you publish all your library’s artifacts to Maven Central or Jcenter repositories, you are simplifying your users configuration; because they won’t have to add custom repositories to their build .gradle files.

You can read more about how to publish on Maven Central here but take into account that you must be the owner of the domain you choose as group id for your dependencies.

The latter tips work for both open source or private libraries. Here are some extra tips that work exclusively for open source libraries.

6. Contributing README

If you use GitHub to host your library code, you can include a file .github/ with contribution guidelines. Then, whenever a contributor opens a pull request or creates an issue, they will see your guidelines file.

Contributing docs detail the specifics about how a project’s maintainer would like to see patches or features contributed. This can include what tests to write, code syntax style or areas to focus on for patches.

You can see an example here and get more info here.

7. Git Branching & Tags convention

It’s so important that you define and make public your git branching & tags strategy, so your collaborators can better know where to work. For example, It will let them know which branch is the more stable version of your library and where is the latest cutting-edge version of it.

8. Public continuous integration

Having a public continuous integration tool will let your library users and contributors know about the stability of your branches.

CircleCI is an excellent continuous integration tool and it’s free for open source projects. It’s also integrated with the pull request mechanism of Github and you can include a CircleCI badge with your branch build status on your README file

 CircleCI build status badge

9. Public issue tracker

A public issue tracker that lets your users and collaborators upload bugs, features requests or improvements is a nice idea to promote collaboration.

If you use GitHub as git repository, GitHub Issues is a good start. If your project is big or more complex, you maybe will need a more sophisticated tool like Jira o Redmine.

10. Publish Sources

Don’t forget to publish your source code on your dependencies repository (i.e. Maven Central or Jcenter). This good practice will help your user’s IDE to automatically load the sources. This is very helpful to increase the understanding of the internals of your library and also encouraging proper usage of it.

Adding these lines to your build.gradle will automatically upload your sources as part of the uploadArchives Gradle task.

task('androidSourcesJar', type: Jar) {
classifier = 'sources'

artifacts {
archives project.tasks.androidSourcesJar

This article contains Affiliate Links. If you purchase anything after clicking an affiliate link, I may receive some compensation.

If you want to learn Android, here you have some recommended books


Popular Posts

Circle CI + Android configuration tips

Versioning Android apps

Say bye-bye to Android Jetifier