How to improve your Android Library
10 best practices & tips
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_'
}
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-debug.aar
- 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 keepachangelog.com 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 https://github.com/releaseshub/releases-hub-gradle-plugin/releases
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/CONTRIBUTING.md 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
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'
from android.sourceSets.main.java.sourceFiles, android.sourceSets.debug.java.sourceFiles
}
artifacts {
archives project.tasks.androidSourcesJar
}You can follow our DipienMedium Publication for more productivity tools & ideas for Android, Kotlin & Gradle developers.
If you enjoyed this article, you might get value out of these as well!
