From c994f3f11e3fd017365ebab1e47acff8ec7b0db2 Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 09:39:58 +0200 Subject: [PATCH 1/7] chore: pin Flutter to 3.41.9 via FVM and add CONTRIBUTING.md Pins the Flutter SDK in .fvmrc so all contributors and CI build against the same version, and adds a CONTRIBUTING guide covering branching, commit/PR conventions, and code style. Co-Authored-By: Claude Opus 4.7 (1M context) --- .fvmrc | 3 +++ CONTRIBUTING.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 .fvmrc create mode 100644 CONTRIBUTING.md diff --git a/.fvmrc b/.fvmrc new file mode 100644 index 00000000..084b2bc5 --- /dev/null +++ b/.fvmrc @@ -0,0 +1,3 @@ +{ + "flutter": "3.41.9" +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5a529bc6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing + +Thanks for contributing to the CARP study app. This guide covers how to propose changes; it does not cover local environment setup (see the README for that). + +## Branching + +- `master` — released code; tagged versions are cut from here. +- `develop` — integration branch. **Open all PRs against `develop`.** +- Feature branches — named `feature/`, `fix/`, or `chore/`. + +## Flutter version + +This repo pins the Flutter SDK with [FVM](https://fvm.app/). The version is declared in `.fvmrc` and **must** be used for development and CI so builds are reproducible. Run Flutter commands as `fvm flutter ...`. + +## Commit messages + +- Use the imperative mood ("add X", "fix Y", not "added X"). +- Keep the subject under 72 characters. +- Reference an issue in the body when relevant (`Refs #123`, `Closes #123`). + +## Pull requests + +Before opening a PR: + +1. Rebase on the latest `develop`. +2. Run `fvm flutter analyze` and `fvm dart format .` — both must be clean. +3. Run `fvm flutter test` — all tests must pass. +4. Build and smoke-test the change in at least the `local` and `dev` deployment modes (see `launch.json`). Note in the PR description which modes you tested. + +When opening the PR: + +- **Title** — short and descriptive, prefixed with the change type: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`. Example: `fix: handle null study id during consent`. +- **Description** — what changed and *why*. Link the issue it resolves. Call out any user-visible behavior change, migration concern, or risk to other deployment modes. +- **Scope** — one logical change per PR. Split unrelated fixes into separate PRs. +- **Screenshots / recordings** — required for any UI change. +- **Reviewers** — request at least one reviewer from the core team. + +## Code style + +- Dart formatter line length: 120 (configured in `analysis_options.yaml`). +- Follow the lints in `analysis_options.yaml`; do not suppress warnings without a comment explaining why. +- Prefer small, focused widgets and pure functions; avoid adding state to a widget when a parent already owns it. + +## Reporting issues + +Bugs and improvement suggestions go through the GitHub issue templates in `.github/ISSUE_TEMPLATE/`. Do not file security issues in public issues — see `SECURITY.md` if present, or email the maintainers directly. From 29cbd95ca72ffed4b6737467a81fa95d827396d3 Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 10:34:09 +0200 Subject: [PATCH 2/7] docs(contributing): document test staging branch and soften test requirement Adds the `test` branch to the branching model as the staging branch between develop and master, and rewords the test-suite step to reflect that current coverage is minimal. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a529bc6..7abc8ae1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,9 +5,12 @@ Thanks for contributing to the CARP study app. This guide covers how to propose ## Branching - `master` — released code; tagged versions are cut from here. +- `test` — staging branch. `develop` is promoted here for QA / pre-release validation before it reaches `master`. Do not open feature PRs against `test`. - `develop` — integration branch. **Open all PRs against `develop`.** - Feature branches — named `feature/`, `fix/`, or `chore/`. +Flow: `feature/*` → `develop` → `test` (staging) → `master` (release). + ## Flutter version This repo pins the Flutter SDK with [FVM](https://fvm.app/). The version is declared in `.fvmrc` and **must** be used for development and CI so builds are reproducible. Run Flutter commands as `fvm flutter ...`. @@ -24,7 +27,7 @@ Before opening a PR: 1. Rebase on the latest `develop`. 2. Run `fvm flutter analyze` and `fvm dart format .` — both must be clean. -3. Run `fvm flutter test` — all tests must pass. +3. Run `fvm flutter test` — the suite is minimal today, but keep it green and add tests for new model logic where practical. 4. Build and smoke-test the change in at least the `local` and `dev` deployment modes (see `launch.json`). Note in the PR description which modes you tested. When opening the PR: From 502dd71c91b4b979592da94756c7f6ff7ad8b858 Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 10:36:50 +0200 Subject: [PATCH 3/7] docs(issue-template): require concrete repro details on bug reports Adds fields for the affected screen, reproducibility frequency, and the study/deployment configuration that triggers the bug, and adds an optional `flutter doctor -v` section for developer reporters. The previous template did not capture where in the app the bug occurred or the configuration needed to reproduce it. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/ISSUE_TEMPLATE/bugfix.yml | 54 ++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bugfix.yml b/.github/ISSUE_TEMPLATE/bugfix.yml index 26e68f3e..b6048bcc 100644 --- a/.github/ISSUE_TEMPLATE/bugfix.yml +++ b/.github/ISSUE_TEMPLATE/bugfix.yml @@ -68,6 +68,15 @@ body: validations: required: true + - type: input + id: affected-screen + attributes: + label: Affected Screen / Feature + description: Where in the app did the bug happen? Be specific — name the screen, tab, or feature. + placeholder: "e.g., Study consent screen, Heart rate task, Settings → Account" + validations: + required: true + - type: textarea id: bug-description attributes: @@ -81,15 +90,42 @@ body: id: reproduction-steps attributes: label: Steps to Reproduce - description: How can we reproduce this issue? Be specific and detailed. + description: | + How can we reproduce this issue? Be specific — every step a fresh install needs to hit the same bug. + Include the exact account / study / invitation code used, whether you were logged in, and any toggles or permissions that were on/off. value: | - 1. Go to '...' - 2. Click on '...' - 3. Scroll down to '...' + 1. Start from '...' (fresh install? logged in? which study/invitation?) + 2. Go to '...' + 3. Tap on '...' 4. Observe the error validations: required: true + - type: dropdown + id: reproducibility + attributes: + label: Reproducibility + description: How consistently does this bug occur when following the steps above? + options: + - Always (100%) + - Often (more than half the time) + - Sometimes (less than half the time) + - Once (could not reproduce) + validations: + required: true + + - type: textarea + id: configuration + attributes: + label: Study / Protocol Configuration + description: | + If the bug depends on a specific study, deployment, sampling package, or device configuration, describe (or paste) it here. Include the deployment ID / invitation code if applicable. + placeholder: | + - Study: ... + - Deployment ID / invitation code: ... + - Sampling packages enabled: ... + - Paired external devices (Polar, Movesense, etc.): ... + - type: textarea id: expected-behavior attributes: @@ -118,6 +154,16 @@ body: [Paste your logs here] The text will be automatically formatted into code. + - type: textarea + id: flutter-doctor + attributes: + label: Flutter Doctor Output + description: | + Developer reporters only — paste the output of `fvm flutter doctor -v` (or `flutter doctor -v` if not using FVM). Skip this section if you're reporting as an end user. + render: shell + placeholder: | + [Paste `fvm flutter doctor -v` output here] + - type: textarea id: screenshots attributes: From 1b48c8fa2a3268c1bacbdc04ba09703c5be1a48f Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 15:23:21 +0200 Subject: [PATCH 4/7] docs(issue-template): drop web/desktop platform options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The app only targets iOS and Android — there are no web, macOS, Windows, or Linux build directories and no CI or release pipelines for them. Removes the dead options and reworks the deployment-mode labels to be platform-neutral. --- .github/ISSUE_TEMPLATE/bugfix.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bugfix.yml b/.github/ISSUE_TEMPLATE/bugfix.yml index b6048bcc..d16d8ec9 100644 --- a/.github/ISSUE_TEMPLATE/bugfix.yml +++ b/.github/ISSUE_TEMPLATE/bugfix.yml @@ -31,8 +31,6 @@ body: options: - iOS - Android - - Web - - Desktop - Both iOS and Android validations: required: true @@ -61,9 +59,9 @@ body: label: App Deployment Mode description: How was the app deployed to your device? options: - - Production (App Store/Play Store) - - TestFlight/Beta - - Development (Local) + - Production (App Store / Play Store) + - TestFlight (iOS) / Internal Testing (Play Store, Android) + - Development (Local build via Xcode / Android Studio / Flutter CLI) - Other (specify in additional info) validations: required: true From f6c57ff787798e7866f5a4d31a4f8624a4b02d23 Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 15:24:17 +0200 Subject: [PATCH 5/7] docs(issue-template): drop deployment mode field --- .github/ISSUE_TEMPLATE/bugfix.yml | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bugfix.yml b/.github/ISSUE_TEMPLATE/bugfix.yml index d16d8ec9..4c614935 100644 --- a/.github/ISSUE_TEMPLATE/bugfix.yml +++ b/.github/ISSUE_TEMPLATE/bugfix.yml @@ -53,19 +53,6 @@ body: validations: required: true - - type: dropdown - id: deployment-mode - attributes: - label: App Deployment Mode - description: How was the app deployed to your device? - options: - - Production (App Store / Play Store) - - TestFlight (iOS) / Internal Testing (Play Store, Android) - - Development (Local build via Xcode / Android Studio / Flutter CLI) - - Other (specify in additional info) - validations: - required: true - - type: input id: affected-screen attributes: From 8173131037e1dcdfcabc42ab285badcdf8c8b495 Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 15:24:48 +0200 Subject: [PATCH 6/7] docs(issue-template): drop device model field --- .github/ISSUE_TEMPLATE/bugfix.yml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bugfix.yml b/.github/ISSUE_TEMPLATE/bugfix.yml index 4c614935..edabbdd3 100644 --- a/.github/ISSUE_TEMPLATE/bugfix.yml +++ b/.github/ISSUE_TEMPLATE/bugfix.yml @@ -35,15 +35,6 @@ body: validations: required: true - - type: input - id: device-model - attributes: - label: Device Model - description: What is the specific device model you're using? - placeholder: "e.g., iPhone 12 Pro, Samsung Galaxy S21" - validations: - required: true - - type: input id: os-version attributes: From 486a2b593670891c662d63a3875de37fc566eb54 Mon Sep 17 00:00:00 2001 From: Zeroupper Date: Mon, 18 May 2026 15:29:38 +0200 Subject: [PATCH 7/7] docs(issue-template): emphasise that more detail speeds up triage --- .github/ISSUE_TEMPLATE/bugfix.yml | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bugfix.yml b/.github/ISSUE_TEMPLATE/bugfix.yml index edabbdd3..f66c348f 100644 --- a/.github/ISSUE_TEMPLATE/bugfix.yml +++ b/.github/ISSUE_TEMPLATE/bugfix.yml @@ -9,8 +9,8 @@ body: attributes: value: | # Bug Report Form - Thank you for taking the time to report a bug. Please provide as much detail as possible to help us investigate and resolve the issue quickly. - + Thank you for taking the time to report a bug. **The more information you provide, the faster the issue will be resolved** — fill in every field you can, even the optional ones. + **Note:** Fields marked with an asterisk (*) are required. - type: input @@ -19,8 +19,6 @@ body: label: App Version description: Which version of the app are you currently using? placeholder: "e.g. 1.5" - validations: - required: true - type: dropdown id: platform @@ -77,19 +75,6 @@ body: validations: required: true - - type: dropdown - id: reproducibility - attributes: - label: Reproducibility - description: How consistently does this bug occur when following the steps above? - options: - - Always (100%) - - Often (more than half the time) - - Sometimes (less than half the time) - - Once (could not reproduce) - validations: - required: true - - type: textarea id: configuration attributes: