fix guidelines and ci

Author: Mikhail Orlov

.github/workflows/ci.yml

@@ -36,6 +36,9 @@ jobs:
       - name: Get dependencies
         run: flutter pub get
 
+      - name: Check no outdated deps message
+        run: bash script/check_no_outdated_deps.sh
+
       - name: Generate l10n
         run: flutter gen-l10n
 
@@ -65,7 +68,7 @@ jobs:
         run: flutter gen-l10n
 
       - name: Run unit tests
-        run: flutter test test/domain test/storage test/router test/l10n
+        run: flutter test test/domain test/storage test/router test/l10n test/deps_no_outdated_message_test.dart
 
   test-widget:
     name: Widget tests

CONTRIBUTING.md

@@ -121,7 +121,7 @@ After dependency upgrades (e.g. `flutter_timezone`), run at least `flutter pub g
 3. Ensure **all CI jobs pass**, including **Build Android APK**. If you cannot build APK locally, push and check the PR pipeline. Build APK is the only gate for Android config (desugaring, etc.).
 4. Do not downgrade plugins with native code to versions that use the old Flutter embedding (e.g. `flutter_timezone` must stay **^5.0.0** or higher; see [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md)).
 
-**"N packages have newer versions" during build:** Run `make outdated` (or `flutter pub outdated`) to see which dependencies can be updated. Prefer updating direct dependencies and following the upgrade checklist above so the message stays minimal. See [docs/DEPENDENCIES.md §6](docs/DEPENDENCIES.md) for details.
+**"N packages have newer versions" during build:** A **test** (`test/deps_no_outdated_message_test.dart`) and a **CI step** (`script/check_no_outdated_deps.sh`) fail when this message appears. To fix: run `make outdated` (or `flutter pub outdated`), update `pubspec.yaml` or `dependency_overrides`, then `make check-deps` or `make test`. See [docs/DEPENDENCIES.md §6](docs/DEPENDENCIES.md).
 
 ---
 
@@ -136,6 +136,7 @@ What the guidelines require is enforced as follows. **If it can be automated, it
 | Unit tests pass | **CI Unit tests** — `flutter test test/domain test/storage test/router test/l10n`. |
 | Widget tests pass | **CI Widget tests** — `flutter test test/screens test/helpers`. |
 | Web builds | **CI Build Web** — `flutter build web --release`. |
+| No "packages have newer versions" message after pub get | **CI Lint** — `script/check_no_outdated_deps.sh`. **Unit tests** — `test/deps_no_outdated_message_test.dart`. Locally: `make check-deps`. |
 | Android APK builds (incl. Gradle/native config) | **CI Build Android APK** — `flutter build apk --release`. Catches missing desugaring, wrong embedding, etc. |
 | New/changed behavior has tests | Process: add or update tests in the same PR; CI runs the full test suite. |
 | Dependency upgrades: native config applied | **CI Build Android APK** fails if e.g. desugaring is missing. No separate test; the build is the gate. |

Makefile

@@ -1,7 +1,7 @@
 # Take Your Meds — Make targets
 # Requires: Flutter SDK on PATH (for run/build/test), Docker (for run-chrome-docker).
 
-.PHONY: help run run-chrome build-android build-ios run-chrome-docker test test-unit test-widget test-integration clean deps gen-l10n analyze format check outdated
+.PHONY: help run run-chrome build-android build-ios run-chrome-docker test test-unit test-widget test-integration clean deps gen-l10n analyze format check check-deps outdated
 
 help:
 	@echo "Take Your Meds — targets:"
@@ -19,6 +19,7 @@ help:
 	@echo "  analyze           Run static analysis (flutter analyze lib test)"
 	@echo "  format            Format lib and test (dart format). Run before every commit."
 	@echo "  check             Same as CI Lint job: analyze + format check. Fails if not formatted."
+	@echo "  check-deps        Fail if 'flutter pub get' reports packages with newer versions incompatible with constraints."
 	@echo "  outdated          List outdated packages (flutter pub outdated). Run periodically to keep deps current."
 	@echo "  clean             Clean build artifacts"
 
@@ -41,7 +42,7 @@ test:
 	flutter test
 
 test-unit:
-	flutter test test/domain test/storage test/router test/l10n
+	flutter test test/domain test/storage test/router test/l10n test/deps_no_outdated_message_test.dart
 
 test-widget:
 	flutter test test/screens test/helpers
@@ -65,6 +66,9 @@ check:
 	flutter analyze lib test
 	dart format --set-exit-if-changed lib test
 
+check-deps:
+	bash script/check_no_outdated_deps.sh
+
 outdated:
 	flutter pub outdated
 

README.md

@@ -69,6 +69,7 @@ Key paths:
 | `make analyze` | Run static analysis (lib + test) |
 | `make format` | Format `lib` and `test` (run before every commit; CI checks this) |
 | `make check` | Same as CI Lint: analyze + format check |
+| `make check-deps` | Fail if `flutter pub get` reports "packages have newer versions incompatible with constraints" (same as CI; see test `deps_no_outdated_message_test.dart`) |
 | `make outdated` | List outdated packages; run periodically to keep deps current (see docs/DEPENDENCIES.md) |
 | `make clean` | Clean build artifacts |
 

docker/docker-compose.yml

@@ -92,11 +92,17 @@ Summary: **Dependency upgrades that touch native code must be validated by a ful
 
 When you run `flutter pub get` or build the app, you may see: *"N packages have newer versions incompatible with dependency constraints. Try \`flutter pub outdated\` for more information."*
 
-**What to do:**
+**Enforcement:** A **test** and a **CI step** fail when this message appears, so every developer and CI see the failure until it is fixed:
 
-1. **Run `flutter pub outdated`** (or `make outdated` if available). It lists direct and transitive dependencies and shows which can be upgraded within current constraints ("Upgradable") or need a constraint change ("Resolvable" / "Latest").
-2. **Prioritize direct dependencies.** Update `pubspec.yaml` constraints for our direct dependencies so they resolve to current, compatible versions. Follow the upgrade checklist in §3 and the native-plugin rules in §2.
-3. **Transitive dependencies** (e.g. `characters`, `meta`, `matcher`) are pulled in by the SDK or other packages. We do not list them in `pubspec.yaml`; they are upgraded when we upgrade Flutter or the direct packages. Do not add overrides unless necessary to fix a security or build issue.
-4. **After any dependency change:** run `make format`, `make check`, `make test`, and ensure CI (including Build Android APK) passes.
+- **Test:** `test/deps_no_outdated_message_test.dart` runs `flutter pub get` and fails if the output contains that message. It is run with unit tests (`make test-unit` or `flutter test test/... test/deps_no_outdated_message_test.dart`).
+- **CI:** The Lint job runs `script/check_no_outdated_deps.sh` after `flutter pub get`; the script exits 1 if the message is present.
+- **Locally:** Run `make check-deps` to run the same check without running the full test suite.
 
-This keeps the "N packages have newer versions" message to a minimum and avoids accumulating technical debt. Prefer upgrading one or a few related packages per change, with tests and CI green.
+**What to do when the test or check fails:**
+
+1. **Run `flutter pub outdated`** (or `make outdated`). It lists which packages have newer versions and whether they are "Upgradable" or need a constraint change.
+2. **Update direct dependencies** in `pubspec.yaml` to compatible newer versions where possible. Follow the upgrade checklist in §4.
+3. **Transitive dependencies** that still show "incompatible with constraints" can be pinned to a newer version via **dependency_overrides** in `pubspec.yaml` (see current overrides in this project for characters, matcher, meta, etc.). Use overrides sparingly and only for transitive deps we cannot fix by upgrading direct deps.
+4. After changes: run `make format`, `make check`, `make test` (or at least `make check-deps`), and ensure CI passes.
+
+This keeps the "N packages have newer versions" message gone and ensures the test and CI stay green.

docs/DEPENDENCIES.md

@@ -26,13 +26,13 @@ packages:
     source: hosted
     version: "2.1.2"
   characters:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: characters
-      sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803
+      sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b
       url: "https://pub.dev"
     source: hosted
-    version: "1.4.0"
+    version: "1.4.1"
   clock:
     dependency: transitive
     description:
@@ -293,29 +293,29 @@ packages:
     source: hosted
     version: "1.3.0"
   matcher:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: matcher
-      sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2
+      sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6"
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.17"
+    version: "0.12.18"
   material_color_utilities:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: material_color_utilities
-      sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec
+      sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b"
       url: "https://pub.dev"
     source: hosted
-    version: "0.11.1"
+    version: "0.13.0"
   meta:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: meta
-      sha256: "23f08335362185a5ea2ad3a4e597f1375e78bce8a040df5c600c8d3552ef2394"
+      sha256: "9f29b9bcc8ee287b1a31e0d01be0eae99a930dbffdaecf04b3f3d82a969f296f"
       url: "https://pub.dev"
     source: hosted
-    version: "1.17.0"
+    version: "1.18.1"
   mocktail:
     dependency: "direct dev"
     description:
@@ -341,13 +341,13 @@ packages:
     source: hosted
     version: "1.0.0"
   objective_c:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: objective_c
-      sha256: "983c7fa1501f6dcc0cb7af4e42072e9993cb28d73604d25ebf4dab08165d997e"
+      sha256: "100a1c87616ab6ed41ec263b083c0ef3261ee6cd1dc3b0f35f8ddfa4f996fe52"
       url: "https://pub.dev"
     source: hosted
-    version: "9.2.5"
+    version: "9.3.0"
   path:
     dependency: "direct main"
     description:
@@ -610,21 +610,21 @@ packages:
     source: hosted
     version: "1.2.2"
   test_api:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: test_api
-      sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55
+      sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.7"
+    version: "0.7.9"
   timezone:
     dependency: "direct main"
     description:
       name: timezone
-      sha256: dd14a3b83cfd7cb19e7888f1cbc20f258b8d71b54c06f79ac585f14093a287d1
+      sha256: "784a5e34d2eb62e1326f24d6f600aaaee452eb8ca8ef2f384a59244e292d158b"
       url: "https://pub.dev"
     source: hosted
-    version: "0.10.1"
+    version: "0.11.0"
   typed_data:
     dependency: transitive
     description:

pubspec.lock

@@ -51,6 +51,17 @@ dev_dependencies:
   flutter_lints: ^6.0.0
   mocktail: ^1.0.4
 
+# Keep transitive deps at latest compatible to avoid "packages have newer versions"
+# message. See script/check_no_outdated_deps.sh and test/deps_no_outdated_message_test.dart.
+dependency_overrides:
+  characters: ^1.4.1
+  matcher: ^0.12.18
+  material_color_utilities: ^0.13.0
+  meta: ^1.18.0
+  objective_c: ^9.3.0
+  test_api: ^0.7.9
+  timezone: ^0.11.0
+
 # The following section is specific to Flutter packages.
 flutter:
   generate: true

pubspec.yaml

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Fail if `flutter pub get` prints the "packages have newer versions incompatible
+# with dependency constraints" message. Used in CI and locally (make check-deps)
+# so that developers and bots see a clear failure until dependencies are updated.
+set -e
+
+out=$(flutter pub get 2>&1) || true
+echo "$out"
+
+if echo "$out" | grep -q "packages have newer versions incompatible with dependency constraints"; then
+  echo ""
+  echo "FAIL: flutter pub get reported packages with newer versions incompatible with constraints."
+  echo "Run: make outdated   (or flutter pub outdated)"
+  echo "Then update pubspec.yaml / dependency_overrides and see docs/DEPENDENCIES.md"
+  exit 1
+fi
+exit 0

script/check_no_outdated_deps.sh

@@ -38,6 +38,10 @@ This file describes what each test file and each test does. Use it for QA and on
 - **notification action labels** — The strings for "OK", "Skip", "Postpone 10 min", "Postpone 30 min" come from the app's localization (ARB), not hardcoded.
 - **notification body** — The reminder body text ("Time to take your medication") also comes from localization.
 
+### `deps_no_outdated_message_test.dart` — No "packages have newer versions" message
+
+- **pub get does not report packages with newer versions incompatible with constraints** — Runs `flutter pub get` and fails if the output contains the "packages have newer versions incompatible with dependency constraints" message. Ensures developers and CI see a failing test until dependencies are updated (run `make outdated`, update pubspec or dependency_overrides). Also enforced by CI step `script/check_no_outdated_deps.sh` and locally by `make check-deps`.
+
 ---
 
 ## Widget tests (screens with fake data)