Developing an application with open source comes with its own specificities. Of course, you can just built it and share the code online. But if you want others to understand it and contribute, some best practices are expected.

We have our experience with open source Android apps: Card Case, Envelop and Relaynet; plus some open source libraries as well. Now we're sharing the strategies we've used or seen so far.

Again, none are mandatory or need to be there right from the start. But they are important as your project starts to get attention. They build trust and incentivise contributions. Plus, most of them are also good practices to have, even on closed source projects.

Documentation

Readme

The project README file is the first thing someone sees. It should, at least, include a description of the project, and how to use/run it. You can get fancy and include graphics or screenshots, to make it more inviting. When in doubt, you should err on the side of more information.

Contributing

An important aspect of open source is getting external contributions. Help out by specifying how others can contribute to the project. What should they include in issues raised or pull-requests. This information can be inside the Readme file, but it often sits on a CONTRIBUTING file in the root of the project. Here's a good example. On platforms like Github you can set templates for issues and pull-request, to help improve the quality of contributions.

Versioning

There are many strategies for keeping track of app versions. Semantic Versioning is a must have for libraries, but also popular for apps. Some strategies can be automated, based on commits and timestamps. Pick any strategy you prefer, as long as you document it and use it consistently.

Changelog

Keep a list of changes made for each version, so users can keep track of what is going on. This can be automated, using commit messages and PRs, like with Conventional Commits. This usually sits on the repository in a CHANGELOG file, but you can keep them elsewhere, like a releases tab tied to the version control tags.

License

If you want others to improve or build upon your software, it's important to license it. Otherwise, even if you make your code public, it's bound to copyright law, all rights reserved. If you don't know much about open source licenses, here's a good website to help you pick the right license: Choose a license.

Integrity

Testing

Automated tests are a programming best practice. But they are even more valuable if you're expecting outside code submissions. It gives contributors confidence in their changes, and avoids regressions.

Test coverage

Besides automated tests, it's common to include some test code coverage stats. They're useful when you want to know if your projects need more tests. But also warn you if some change accidentally led to code no longer being tested.

Lint / Code Style

To save everyone's time, avoid common bugs and keep the repository clean. It's a good idea to run some checks before accepting code changes. The most common check ensures the code is following a defined style. You can even share that code style beforehand, so contributors can use it in their code editor. But nowadays there are lints for everything: catch potential bugs, outdated dependencies, security malpractices, etc..

Continuous Integration

To ensure all the above checks are passing, it's a great idea to run them as frequently as possible. That's where continuous integration comes in place. You can make sure that any PR submitted has all tests and checks green, before merging it into the project. There are tons of solutions for this, and even code hosting platforms like Github and Gitlab have their own.

Continuous Deployment

The next step after Continuous Integration is Continuous Deployment, to save you extra time. You can use it for building a test version of the app for every PR, for quality assurance purposes. Or to automatically deploy a new version of the app when a PR gets merged, or a new git tag is pushed. Some apps are easier to deploy automatically than others, but there are tools for almost anything. Fastlane is a popular tool for automating deploys.

Reproducible builds

A lot of software is used in a packaged form, where code either gets compiled, minified or altered in some other way. How can users ensure that software matches the source code that's shared publicly? That's why you need Reproducible Builds. This is an area still under active development, but that we expect to become more popular in the near future.