ODK Collect

ODK Collect is an Android app for filling out forms. It is designed to be used in resource-constrained environments with challenges such as unreliable connectivity or power infrastructure. ODK Collect is part the ODK project, a free and open-source set of tools which help organizations author, field, and manage mobile data collection solutions. Learn more about ODK and its history here and read about example ODK deployments here.

ODK Collect renders forms that are compliant with the ODK XForms standard, a subset of the XForms 1.1 standard with some extensions. The form parsing is done by the JavaRosa library which Collect includes as a dependency.

Please note that the master branch reflects ongoing development and is not production-ready.

Learn more about ODK Collect
Release cycle
Downloading builds
Suggesting new features
Contributing
- Contributing code
- Contributing translations
Developing
Creating signed releases for Google Play Store

Learn more about ODK Collect

ODK website: https://getodk.org
ODK Collect usage documentation: https://docs.getodk.org/collect-intro/
ODK forum: https://forum.getodk.org
ODK developer Slack chat: https://slack.getodk.org

Release cycle

The work to be done is continuously revised and prioritized in the backlog by the Collect team. The majority of this is influenced by the priorities in the ODK roadmap. Releases are planned to happen every 2-3 months (resulting in ~4 releases a year). This goal is to balance the pace of delivery with keeping things stable for users while also minimizing the risk in each release.

Sometimes issues will be assigned to core team members before they are actually started (moved to "in progress") to make it clear who's going to be working on what.

Once the majority of high risk or visible work is done for a release, a new beta will then be released to the Play Store by @lognaturel and that will be used for regression testing by @getodk/testers. If any problems are found, the release is blocked until we can merge fixes. Regression testing should continue on the original beta build (rather than a new one with fixes) unless problems block the rest of testing. Once the process is complete, @lognaturel pushes the releases to the Play Store following these instructions.

Fixes to a previous release should be merged to a "release" branch (v2023.2.x for example) so as to leave master available for the current release's work. If hotfix changes are needed in the current release as well then these can be merged in as a PR after hotfix releases (generally easiest as a single PR for the whole hotfix release). This approach can also be used if work for the next release starts before the current one is out - the next release continues on master while the release is on a release branch.

At the beginning of each release cycle, @grzesiek2010 updates all dependencies that have compatible upgrades available and ensures that the build targets the latest SDK.

Downloading builds

Per-commit debug builds can be found on CircleCI. Login with your GitHub account, click the build you'd like, then find the APK in the Artifacts tab.

If you are looking to use ODK Collect, we strongly recommend using the Play Store build. Current and previous production builds can be found in Releases.

Suggesting new features

We try to make sure that all issues in the issue tracker are as close to fully specified as possible so that they can be closed by a pull request. Feature suggestions should be described in the forum Features category and discussed by the broader user community. Once there is a clear way forward, issues should be filed on the relevant repositories. More controversial features will be discussed as part of the Technical Steering Committee's roadmapping process.

Contributing code

Any and all contributions to the project are welcome. ODK Collect is used across the world primarily by organizations with a social purpose so you can have real impact!

Issues tagged as good first issue should be a good place to start. There are also currently many issues tagged as needs reproduction which need someone to try to reproduce them with the current version of ODK Collect and comment on the issue with their findings.

If you're ready to contribute code, see the contribution guide.

Contributing translations

If you know a language other than English, consider contributing translations through Transifex.

Translations are updated right before the first beta for a release and before the release itself. To update translations, download the zip from https://explore.transifex.com/getodk/collect/. The contents of each folder then need to be moved to the Android project folders. A quick script like the one in this gist can help. We currently copy everything from Transifex to minimize manual intervention. Sometimes translation files will only get comment changes. When new languages are updated in Transifex, they need to be added to the script above. Additionally, ApplicationConstants.TRANSLATIONS_AVAILABLE needs to be updated. This array provides the choices for the language preference in settings. Ideally the list could be dynamically generated.

Setting up your development environment

Download and install Git and add it to your PATH
Download and install Android Studio
Fork the collect project (why and how to fork)
Clone your fork of the project locally. At the command line:
```
 git clone https://github.com/YOUR-GITHUB-USERNAME/collect
```
If you prefer not to use the command line, you can use Android Studio to create a new project from version control using https://github.com/YOUR-GITHUB-USERNAME/collect.
Use Android Studio to import the project from its Gradle settings. To run the project, click on the green arrow at the top of the screen.
Windows developers: continue configuring Android Studio with the steps in this document: Developing ODK Collect on Windows.
Make sure you can run unit tests by running everything under collect_app/src/test/java in Android Studio or on the command line:
```
./gradlew testDebug
```
Make sure you can run instrumented tests by running everything under collect_app/src/androidTest/java in Android Studio or on the command line:
```
./gradlew connectedAndroidTest
```
Note: You can see the emulator setup used on CI in .circleci/config.yml.

Customizing the development environment

Changing JVM heap size

You can customize the heap size that is used for compiling and running tests. Increasing these will most likely speed up compilation and tests on your local machine. The default values are specified in the project's gradle.properties and this can be overriden by your user level gradle.properties (found in your GRADLE_USER_HOME directory). An example gradle.properties that would give you a heap size of 4GB (rather than the default 1GB) would look like:

org.gradle.jvmargs=-Xmx4096m

Testing a form without a server

When you first run Collect, it is set to download forms from https://demo.getodk.org/, the demo server. You can sometimes verify your changes with those forms but it can also be helpful to put a specific test form on your device. Here are some options for that:

The All question types form from the default server is here. You can also try example forms and test forms or [make your own](https:/

Collect

Install / Use

README