๐Ÿค Contributing to OSMTracker

November 7, 2025 ยท View on GitHub

Thank you for your interest in contributing! ๐ŸŽ‰
Whether you're fixing a bug, adding a new feature, or improving documentation โ€” all contributions are welcome.

๐Ÿ“š Table of Contents

  1. ๐Ÿ”ฐ Before You Start
  2. ๐Ÿ› ๏ธ How to Run the App (Setup Guide)
  3. ๐Ÿงช Running Tests
  4. ๐ŸŒ Translations
  5. ๐Ÿง‘โ€๐Ÿ’ป Git Workflow (GitFlow)
  6. ๐Ÿ‘ถ New Contributor Quick Guide (For Beginners)
  7. ๐Ÿ“œ Code Style & Commit Guidelines
  8. ๐Ÿš€ How to Submit a Pull Request
  9. ๐Ÿ’ฌ Community & Support

๐Ÿ”ฐ 1. Before You Start

  • Make sure you have Git and Android Studio installed.
  • Familiarity with GitFlow is recommended (see below).
  • If you're new to open/free source, check out our beginner section โ†“

๐Ÿ› ๏ธ 2. How to Run the App Locally

# Clone the repository
git clone https://github.com/labexp/osmtracker-android/
cd osmtracker-android
  1. Install Android Studio. - Here is the official guide on how to install it on different operating systems
  2. Open the IDE and click open an existing Android Studio project, then look for the folder where you cloned the repository
  3. Build the project (Ctrl + F9 or the ๐Ÿ› ๏ธ hammer button)

๐Ÿงช 3. Running Tests

This repository has an automated way to run the tests on branches but if you already have the project installed on you computer then you can also run them from a terminal. It's recommended to run the tests locally before making a new pull request to make sure the changes doesn't break any previous functionality. You can run the tests locally as follows:

  • Make sure you are at the root directory of the project
    • $ cd YOUR_PATH/osmtracker-android

๐Ÿ“ฑ Instrumentation Tests (Require Emulator or Device)

  • For running instrumentation tests it's needed to previously start up an emulator (or real device), you can do it from Android Studio but also without it using the command line. For that, you need to move to the Android SDK installation directory and look for a folder called emulator once there, start any already created emulator by typing:
    • $ ./emulator -avd NAME to start the emulator called NAME (run $ ./emulator -list-avds for a valid list of AVD names)
    • When it's up, go back to the root project folder and run the instrumentation tests with
    • $ ./gradlew connectedAndroidTest

โœ… Unit Tests

  • For running the unit tests no emulator or device is needed, just run
    • $ ./gradlew test
  • Now just wait for gradle to run the tests for you, it'll show the results of which tests passed or failed when it's finished

๐ŸŒ 4. Translations

OSMTracker is translated using Transifex (see the wiki). Once translations are complete, they will be updated via automated Transifex PR.

๐Ÿง‘โ€๐Ÿ’ป 5. Git Workflow (GitFlow)

We use GitFlow branching model:

BranchPurpose
masterStable production releases
developMain development branch
feature/*New features
hotfix/*Quick fixes for production
  • If you want more information, take a look here

๐Ÿ‘ถ 6. New Contributor Quick Guide (Beginner-Friendly)

โœจ If this is your first open-source contribution, start here!

  1. โญ Fork the repository

    After forking, make sure your fork includes all the required branches (especially develop, not only master).

    You can verify this by checking the branches tab in your fork on GitHub.

  2. ๐Ÿ“ฅ Clone your fork

    git clone https://github.com/YOUR_USERNAME/osmtracker-android.git

  3. ๐Ÿ”„ (Optional) Add upstream to stay updated

    git remote add upstream https://github.com/labexp/osmtracker-android.git

  4. ๐ŸŒฑ Create a branch

    git checkout develop
git checkout -b feature/your-feature-name

  5. โœ๏ธ Make changes + commit (atomic commits)

  6. ๐Ÿš€ Push your branch

  7. ๐Ÿ“ Open a Pull Request (PR)

๐Ÿ“œ 7. Commit Message Convention

Use clear and descriptive commit messages.

โœ… Good:

feat: add option to export GPX file
fix: resolve crash when no GPS signal
docs: update contributing guide

โŒ Bad:

update stuff
fix bug

๐Ÿš€ 8. How to Submit a Pull Request

  1. Push your changes
  2. Go to GitHub โ†’ Open PR
  3. Fill the PR template fully
  4. Wait for review โœ…

โš ๏ธ PRs without a complete template may be rejected.

๐Ÿ’ฌ 9. Community & Support

  • Have questions? Open a Discussion or an Issue
  • (Optional): Join the contributors chat/Telegram.

Let's build something awesome together! ๐Ÿš€