Skip to content

Contribution Guide

Jump to bottom
Simon Oppowa edited this page Jul 15, 2026 · 1 revision

Contribution Guide

Contributions of every kind are welcome — code, translations, bug reports, and documentation. This page gives you the full picture of how contributing to OpenNutriTracker works. The authoritative, always-current versions of the conventions live in the repository itself: CONTRIBUTING.md (conventions) and GettingStarted.md (environment setup). If this page and those files ever disagree, the repository files win.

Table of Contents

  1. Ways to Contribute
  2. Development Setup
  3. Branching & Pull Requests
  4. Code Style & Checks
  5. Adding or Improving Translations
  6. Code Generation
  7. Platform Support Rules
  8. Related Repositories

Ways to Contribute

  • Report bugs — open an issue with steps to reproduce, your device/OS, and what you expected to happen.
  • Suggest features — open an issue describing the use case (the why, not just the what).
  • Improve translations — the app ships in 9 languages, and native-speaker review is always valuable (see translations).
  • Contribute code — bug fixes and features via pull request (see below).
  • Improve documentation — this wiki and the in-repo docs.
  • Improve food data — incorrect product data usually comes from Open Food Facts; correcting it there helps every user.

If you're unsure about anything, open a draft PR or an issue and ask — early feedback is much cheaper than reworking a finished change.

Development Setup

OpenNutriTracker is a Flutter app (Dart), targeting iOS and Android.

  1. Flutter via FVM — the project pins its Flutter version with FVM. After cloning, run fvm install in the repo root; it reads .fvmrc, downloads the right SDK, and creates the .fvm/flutter_sdk symlink that VS Code picks up automatically.
  2. Android SDK / emulator — install via Android Studio (include the command-line tools and a virtual device). A step-by-step Windows 11 walkthrough is in GettingStarted.md.
  3. Environment file — copy the template: cp .env.example .env. The placeholders are fine for a debug build that doesn't need the live food-database backend; to run against your own backend see supabase-self-hosting.md.
  4. Dependencies & codegen: 
    flutter pub get
dart run build_runner build
    Of the generated files, only env.g.dart needs to stay (it's gitignored); revert other visible generated-file changes.
  5. Run — start an emulator and launch a debug session (F5 in VS Code).

The repo also has a justfile with the common tasks — just build, just format, just test, just check_intl, and just ci (the full CI pipeline as a one-shot pre-flight check).

Branching & Pull Requests

All pull requests must target the develop branch — never main. main is reserved for release merges only (one batched develop → main PR per release). A PR opened against main will be repointed to develop before review.

Workflow:

git fetch origin
git checkout -b feature/<short-name> origin/develop
  • Keep changes scoped — smaller, focused PRs are reviewed and merged much faster than sweeping ones.
  • Reference the issue you're addressing in the PR description (e.g. Closes #123).
  • Commit messages: short imperative subject, optionally with a type(scope): prefix, e.g.: 
    feat(activity): add high-intensity interval exercise
fix(home): correct kcal budget after onboarding
    A body explaining the why is welcome but not required for small changes.

Code Style & Checks

  • 120-character line width (configured in analysis_options.yaml).
  • Format with just format before committing — it deliberately targets only lib/core, lib/features, lib/l10n, and test, and skips lib/generated/.
  • Run flutter analyze and just test locally before opening the PR.
  • just ci runs everything CI will run (install, format check, intl check, build, analyze, test).

Adding or Improving Translations

Source strings live in lib/l10n/intl_en.arb; each supported locale has its own ARB file (intl_de.arb, intl_cs.arb, intl_it.arb, intl_pl.arb, intl_sk.arb, intl_tr.arb, intl_uk.arb, intl_zh.arb).

When adding a new string key, in the same PR you must:

  1. Add the key to every ARB file with a real translation (machine translation is acceptable as a starting point; native-speaker review is welcome post-merge). Don't leave the English string as a placeholder.
  2. Add a getter to lib/generated/l10n.dart, following the existing style.
  3. Add a matching MessageLookupByLibrary.simpleMessage(...) entry to each lib/generated/intl/messages_<locale>.dart.
  4. Verify with just check_intl — CI runs the same check and fails the PR if anything is missing.

Important quirk: the files under lib/generated/ say GENERATED CODE - DO NOT MODIFY BY HAND, but in this project they are currently maintained manually — the upstream generator's output conflicts with the repo's 120-character formatting. Do not run intl_translation:generate_from_arb; edit the files by hand until the generation pipeline is reconciled.

Code Generation

Hive type adapters and JSON serialization are produced by build_runner. Run just build after touching any source file with @HiveType, @HiveField, or @JsonSerializable annotations.

Platform Support Rules

The app ships on both iOS and Android, and PRs must keep it that way:

  • Any new dependency must support both platforms — check pub.dev before adding it.
  • Platform-specific code needs a corresponding implementation (or an explicit fallback) on the other platform.
  • A new Android runtime permission needs the matching Info.plist entry on iOS, and vice versa.

Related Repositories

Repository Purpose
OpenNutriTracker The Flutter app itself.
OpenNutriTracker-Backend The multi-source food database (USDA FDC + German BLS): schema, import pipeline, translation tooling. Self-hostable.
OpenNutriTracker.wiki This wiki — documentation contributions welcome via issues/PR discussion.

⚠️ Disclaimer: OpenNutriTracker is not a medical application. All information should be taken with caution — mistakes can happen. Consult a qualified professional for personal medical or dietary advice.

Clone this wiki locally