- Fork repository and work on your fork.
- Create a new PR with a request to merge to the main branch
- If PR is based on issue, then include its number in PR title and add link to it in description
- One pull request should always address one issue or feature
- When contributing a new feature, provide motivation and use-cases describing value it may brings to the project
- Adding video or screenshot is very beneficial, but it's not mandatory
- Make sure any code contributed is covered by test and documented
- Make sure your code is meeting the default Ktlint standards
Dokka is added to the project, so to create (or, better say, update) the docs, you need to run
./gradlew charts:dokkaHtml
on the root dir of the project.
After the task is done, copy the generated docs into ./docs, which can also be done by running
rm -rf ./docs ; cp -r ./charts/build/dokka/html ./docs
Testing is implemented using Shot library. In order to run it against prerecorded results, create at least one of the following emulators:
- tablet: Nexus 10, running API 31
- phone: Pixel 4a, running API 31
For tests to work, make sure you create emulators with default values, as screen size and density must be exactly the same.
Details as to how to run the tests are in the link to the library itself, but to run it against prerecorded screenshots, run the following command:
./gradlew executeScreenshotTests -PdirectorySuffix=$deviceName
where $deviceName is one of:
- Nexus_10_API_31
- Pixel_4a_API_31
Due to differences in graphics between M1 and x86 chips, images appear different to the script and so the tests fail (difference between images can be well above 10%). To human eye they do seem the same, though. This is explained and shown in issue 265. Until this is fixed, there is a way to test stuff at least locally:
- uncomment tests that are commented out because of this issue
- record all the tests
- make the desired changes in the code
- check the new UI state against the pre-recorded screenshots (I suggest removing tolerance if the tests were recorded on your machine!)
- comment the flaky tests out again
- revert the screenshots
- Library does not work with Java 17. The error itself is not as obvious as one might expect, though. To fix the issue, use Java 11.
- Java heap space sometimes needs to be enlarged
- You might encounter INSTALL_FAILED_SHARED_USER_INCOMPATIBLE issue. Here is a shortcut to the answer.