Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (67 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

92 lines (67 loc) · 3.4 KB
Raw

Contributing

Contributions are welcome, including small ones. So are bug reports from people who cannot fix them, a clear account of something going wrong on hardware nobody here owns is worth more than most patches.

Getting it building

git clone --recurse-submodules https://github.com/elasticjava/uxspace.git
cd uxspace/Android
./gradlew installDebug

You need a Rust toolchain with the aarch64-linux-android target and the Android NDK. Everything else Gradle fetches. There is no SDK to request, no account to create and no binary to vendor in: if a build ever asks you for one, that is a bug.

Working without glasses

Most of this can be developed with nothing plugged in. The driver carries its own simulator, modelled on measurements from real hardware rather than on guesses, and it can inject faults: failing cables, load spikes, poor signal:

adb shell am start -n com.uxspace/.MainActivity \
  --ei com.uxspace.extra.SIMULATE_GLASSES 0

Two of the concurrency bugs in this codebase were found by the fault injection and by nothing else, so it is worth running against even when you have the hardware to hand.

What counts as verified

"It compiles" is not verification. Neither, for anything touching the panel or the render path, is "it works in the simulator", the simulator is a good surrogate for logic and a poor one for optics and video links.

./gradlew test              # unit tests, including the ABI and translation guards
./gradlew assembleRelease   # lint runs at abortOnError, and R8 shrinks

If you have the glasses, the measurement harness collects the figures that matter and prints each one beside what the simulator said:

Android/glasses/viture-v2/tools/glasses_measure.sh

Read docs/TESTPLAN.md in the driver repository before the first run. Three things in there will otherwise cost you an evening, and one of them made a perfectly healthy phone look like a dead one.

Two guards worth knowing about

Both exist because the failure they catch is invisible rather than loud.

  • AbiConstantsTest reads the Rust driver's own source and checks the numbers that cross the JNI boundary. Renumber a Rust enum and this fails, rather than the picture quietly coming out wrong.
  • TranslationsTest compares values/strings.xml against values-de/. Add a string in one language and forget the other and this fails, rather than a German phone showing one English label that nobody who wrote the code will ever see.

Style

Match the surrounding code. Comments explain why, not what, the code already says what it does, and a comment repeating it is a second thing to keep true.

Where something was measured, say the number. // 118.9 Hz, counted, not the 120 it is configured for is worth more than // pose rate, and it is the difference between a reader trusting the value and re-deriving it.

Commits

Conventional prefixes: feat:, fix:, docs:, test:, chore:, ci:, refactor:, perf:. The subject line says what changed for a user, not which file was touched.

Reporting something

Issues use templates: please fill them in, particularly the version and the log. For anything involving the panel, adb shell dumpsys display | grep -A2 VITURE says what mode it is actually in, and that is often the entire answer.

Security issues go through private reporting, not a public issue.