Skip to content

QUICKSTART_EN.md

Latest commit

 

History

History
124 lines (88 loc) · 4.22 KB

QUICKSTART_EN.md

File metadata and controls

124 lines (88 loc) · 4.22 KB
Raw

BlindAssist three-minute quick start

Status: current

Last verified: 2026-08-12

This page gets a new contributor from clone to one honest, reviewable result. The three minutes cover orientation and starting a check; the first Android build can take longer while Gradle downloads dependencies.

BlindAssist is a research and accessibility prototype, not a certified mobility or safety device. A successful build does not prove perception quality, user outcomes, or safe navigation.

Before the timer

Install Git, PowerShell 7, JDK 17, and Android SDK Platform 35. On Windows, the maintained wrapper discovers and validates the local toolchain. On Linux, the commands below mirror the public GitHub Actions path; clean-host verification is still tracked as a contributor task.

Do not clone datasets, download research payloads, connect a device, or configure secrets for this quick start.

0:00 — clone and enter the repository

git clone https://github.com/violetljj/blind-assist.git
cd blind-assist
git status --short --branch

Expected result: branch master and no changed files.

0:45 — choose the smallest useful path

Documentation or community contribution

These checks require PowerShell 7 but no Android device:

pwsh -NoProfile -File scripts/check_docs_index.ps1
pwsh -NoProfile -File scripts/check_open_source_readiness.ps1

Android contribution on Windows

Run the bounded preflight before starting Gradle:

pwsh -NoProfile -File scripts/run_android_gradle.ps1 -PreflightOnly

Expected result: the command reaches a successful preflight. If it reports ENV_BLOCKED, fix the named JDK or SDK requirement instead of bypassing the wrapper.

Android contribution on Linux

Use the same focused tasks as CI:

chmod +x ./gradlew
./gradlew --max-workers=2 \
  "-Dorg.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8" \
  :app:testDebugUnitTest :app:lintDebug :app:assembleDebug

This is a CI-validated path, not yet a promise that every Linux workstation is supported. If a clean machine differs, report the distribution, architecture, JDK, Android SDK packages, exact command, and complete error in the setup issue.

2:00 — produce one verifiable result

For a focused Android check on Windows:

pwsh -NoProfile -File scripts/run_android_gradle.ps1 `
  :app:testDebugUnitTest :app:lintDebug :app:assembleDebug

The APK is written to:

app/build/outputs/apk/debug/app-debug.apk

For a documentation-only change, finish with the checks that own that surface:

git diff --check
pwsh -NoProfile -File scripts/check_docs_index.ps1

Run structure, release, permission, default-app, or shared-infrastructure gates only when the change touches that risk. A push by itself does not require an unrelated full-repository gate.

3:00 — pick a bounded first contribution

  • Browse the good first issue queue.
  • Comment on the issue before starting so scope and duplicate work stay visible.
  • Change only the files named in the issue and run its copyable verification commands.
  • Open one focused pull request and report commands, results, remaining gaps, and whether the default app is affected.

Read CONTRIBUTING.md before editing and GOVERNANCE.md before volunteering for review or maintenance. Questions and early ideas belong in GitHub Discussions; security or privacy reports must follow SECURITY.md.

What not to do in a first contribution

  • Do not change the packaged model, permissions, feedback policy, release signing, research gates, or default-app authority unless the issue explicitly permits it.
  • Do not commit raw camera footage, device logs, private data, credentials, restricted datasets, SDK payloads, generated APKs, or artifacts.local/ files.
  • Do not convert UNKNOWN, synthetic evidence, a build result, or a benchmark into a product or safety claim.

The stable module map is in CODE_MAP.md. The full evidence boundary is in RESEARCH_GOVERNANCE.md.