chore: merge main and resolve workflow conflict

Co-authored-by: jjoonleo <67417817+jjoonleo@users.noreply.github.com>

Author: Copilot

.github/workflows/android-play-internal.yml

@@ -1,6 +1,9 @@
 name: Android Play Internal Deploy
 
 on:
+  push:
+    branches:
+      - main
   workflow_dispatch:
     inputs:
       release_notes:
@@ -15,7 +18,7 @@ jobs:
   deploy_internal:
     name: Build and upload internal testing draft
     runs-on: ubuntu-latest
-    environment: release
+    environment: staging
     env:
       ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
       ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
@@ -103,11 +106,26 @@ jobs:
       - name: Test
         run: flutter test
 
+      - name: Derive Android build name
+        run: |
+          app_version="$(sed -n 's/^version: *//p' pubspec.yaml | head -n 1)"
+          build_name="${app_version%%+*}"
+          if [ -z "$build_name" ]; then
+            echo "Unable to derive Android build name from pubspec.yaml version." >&2
+            exit 1
+          fi
+          echo "ANDROID_BUILD_NAME=$build_name" >> "$GITHUB_ENV"
+
       - name: Build Android app bundle
-        run: flutter build appbundle --release --dart-define=REST_API_URL="$REST_API_URL"
+        run: |
+          flutter build appbundle --release \
+            --build-name="$ANDROID_BUILD_NAME" \
+            --build-number="${{ github.run_number }}" \
+            --dart-define=ENV=staging \
+            --dart-define=REST_API_URL="$REST_API_URL"
 
       - name: Prepare Play release notes
-        if: ${{ inputs.release_notes != '' }}
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.release_notes != '' }}
         env:
           RELEASE_NOTES: ${{ inputs.release_notes }}
         run: |
@@ -123,7 +141,7 @@ jobs:
           retention-days: 14
 
       - name: Upload internal testing draft with release notes
-        if: ${{ inputs.release_notes != '' }}
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.release_notes != '' }}
         uses: r0adkll/upload-google-play@v1
         with:
           serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
@@ -134,7 +152,7 @@ jobs:
           whatsNewDirectory: distribution/whatsnew
 
       - name: Upload internal testing draft
-        if: ${{ inputs.release_notes == '' }}
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.release_notes == '' }}
         uses: r0adkll/upload-google-play@v1
         with:
           serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}

.github/workflows/firebase-hosting-merge.yml

@@ -13,7 +13,7 @@ permissions:
 jobs:
   build_and_deploy:
     runs-on: ubuntu-latest
-    environment: release
+    environment: staging
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-java@v1
@@ -35,7 +35,10 @@ jobs:
       - name: Build Web
         env:
           REST_API_URL: ${{ vars.REST_API_URL }}
-        run: flutter build web --release --dart-define=REST_API_URL=$REST_API_URL
+        run: |
+          flutter build web --release \
+            --dart-define=ENV=staging \
+            --dart-define=REST_API_URL=$REST_API_URL
 
       - uses: FirebaseExtended/action-hosting-deploy@v0
         with:

.github/workflows/firebase-hosting-pull-request.yml

@@ -36,7 +36,10 @@ jobs:
       - name: Build Web
         env:
           REST_API_URL: ${{ vars.REST_API_URL }}
-        run: flutter build web --release --dart-define=REST_API_URL=$REST_API_URL
+        run: |
+          flutter build web --release \
+            --dart-define=ENV=dev \
+            --dart-define=REST_API_URL=$REST_API_URL
 
       - uses: FirebaseExtended/action-hosting-deploy@v0
         with:

.github/workflows/flutter_test.yml

@@ -2,22 +2,34 @@ name: Flutter Testing
 on:
   workflow_dispatch:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - "release/**"
+      - "hotfix/**"
+  push:
+    branches:
+      - main
+      - "release/**"
+      - "hotfix/**"
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: subosito/flutter-action@v2
         with:
-          channel: 'stable'
+          flutter-version: "3.32.6"
+          channel: stable
+          cache: true
       - name: install sql
         run: sudo apt-get install sqlite3 libsqlite3-dev
       - name: Install packages
         run: flutter pub get
       - name: Check Flutter version
         run: flutter --version
       - name: Run generator
-        run: flutter pub run build_runner build
+        run: dart run build_runner build --delete-conflicting-outputs
+      - name: Analyze
+        run: flutter analyze
       - name: Run test
-        run: flutter test test
+        run: flutter test

README.md

@@ -81,6 +81,7 @@ The app reads compile-time values from Dart defines in `lib/core/constants/envir
 
 | Define | Required | Used for |
 | --- | --- | --- |
+| `ENV` | Optional | App environment label. Use `dev`, `staging`, or `prod`; defaults to `dev`. |
 | `REST_API_URL` | Yes | Base URL for Dio API calls. |
 | `REST_AUTH_TOKEN` | Optional | Static auth token override for development/test scenarios. |
 | `GOOGLE_RESERVED_CLIENT_ID_IOS` | iOS release/archive only | Reversed iOS Google client ID used as the iOS URL scheme for Google Sign-In. |
@@ -89,16 +90,19 @@ Pass defines directly on Flutter commands:
 
 ```sh
 flutter run -d chrome \
+  --dart-define=ENV=dev \
   --dart-define=REST_API_URL=<api-base-url>
 
 flutter build web --release \
+  --dart-define=ENV=staging \
   --dart-define=REST_API_URL=<api-base-url>
 ```
 
 For iOS release and archive builds, include the Google URL scheme define:
 
 ```sh
 flutter build ios --release \
+  --dart-define=ENV=prod \
   --dart-define=REST_API_URL=<api-base-url> \
   --dart-define=GOOGLE_RESERVED_CLIENT_ID_IOS=<reversed-ios-client-id>
 ```
@@ -165,19 +169,41 @@ flutter test --coverage
 Run the web app locally:
 
 ```sh
-flutter run -d chrome --dart-define=REST_API_URL=<api-base-url>
+flutter run -d chrome \
+  --dart-define=ENV=dev \
+  --dart-define=REST_API_URL=<api-base-url>
 ```
 
 Do not use `npm test`; the root `package.json` script is a placeholder that intentionally fails.
 
 ## Build and Release
 
+This repository uses trunk-based development with release branches:
+
+```text
+main = always test-deployable
+release/* = store candidate
+v* tag = production release source of truth
+hotfix/* = emergency production repair
+```
+
+Normal changes should land through short-lived `feature/*` or `fix/*` branches
+into `main`. Create `release/x.y.z` from `main` for final store QA, cut
+`vX.Y.Z` tags from approved release branches, then merge the release branch back
+to `main`. See [docs/Git.md](docs/Git.md) for the full branch and deployment
+flow.
+
 ### Web
 
-Preview and production web deployments are handled by GitHub Actions and Firebase Hosting. CI uses the `REST_API_URL` GitHub environment variable and builds with:
+Preview and staging web deployments are handled by GitHub Actions and Firebase
+Hosting. Pull requests build with `ENV=dev`; merges to `main` build with
+`ENV=staging`. CI uses the `REST_API_URL` GitHub environment variable and builds
+with:
 
 ```sh
-flutter build web --release --dart-define=REST_API_URL=<api-base-url>
+flutter build web --release \
+  --dart-define=ENV=staging \
+  --dart-define=REST_API_URL=<api-base-url>
 ```
 
 Firebase Hosting deploys `build/web` to project `ontime-c63f1`.
@@ -188,13 +214,15 @@ Build a release APK:
 
 ```sh
 flutter build apk --release \
+  --dart-define=ENV=staging \
   --dart-define=REST_API_URL=<api-base-url>
 ```
 
 Build an app bundle for Play Console upload:
 
 ```sh
 flutter build appbundle --release \
+  --dart-define=ENV=prod \
   --dart-define=REST_API_URL=<api-base-url>
 ```
 
@@ -206,6 +234,7 @@ Build locally:
 
 ```sh
 flutter build ios --release \
+  --dart-define=ENV=prod \
   --dart-define=REST_API_URL=<api-base-url> \
   --dart-define=GOOGLE_RESERVED_CLIENT_ID_IOS=<reversed-ios-client-id>
 ```

docs/Android-Release-Configuration.md

@@ -12,10 +12,11 @@ The release verification workflow decodes this secret to `android/app/src/releas
 
 Use the `Android Play Internal Deploy` GitHub Actions workflow to build a signed
 Android App Bundle and upload it to the Google Play Internal Testing track as a
-draft release. The workflow is manual-only and must be dispatched from `main`.
+draft release. The workflow runs automatically on pushes to `main` and can also
+be dispatched manually from `main`.
 
-Configure a GitHub environment named `release` with required reviewers before
-using the workflow. Store these environment secrets there:
+Configure a GitHub environment named `staging` for internal test distribution.
+Store these environment secrets there:
 
 - `ANDROID_GOOGLE_SERVICES_JSON_B64`: base64-encoded production Android
   Firebase config.
@@ -26,21 +27,33 @@ using the workflow. Store these environment secrets there:
 - `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON`: raw service-account JSON for the Google
   Play Developer API.
 
-Store this environment variable in `release`:
+Store this environment variable in `staging`:
 
-- `REST_API_URL`: production API base URL passed to Flutter with
-  `--dart-define`.
+- `REST_API_URL`: target API base URL passed to Flutter with `--dart-define`.
 
 The deploy workflow runs package install, code generation, generated-file drift
 checking, analysis, tests, and then `flutter build appbundle --release`. It
-uploads the signed `.aab` as a 14-day GitHub Actions artifact and creates a
+derives Android `versionName` from the `pubspec.yaml` version name and supplies
+`${{ github.run_number }}` as Android `versionCode`:
+
+```sh
+flutter build appbundle --release \
+  --build-name=<version name from pubspec.yaml> \
+  --build-number=${{ github.run_number }} \
+  --dart-define=ENV=staging \
+  --dart-define=REST_API_URL="$REST_API_URL"
+```
+
+It uploads the signed `.aab` as a 14-day GitHub Actions artifact and creates a
 draft release on Google Play Internal Testing. If the optional release notes
 input is empty, the workflow uploads without custom release notes.
 
-`pubspec.yaml` remains the source of truth for `version: major.minor.patch+build`.
-Before dispatching the workflow, bump the build number so it is greater than
-every previously uploaded Google Play build for `club.devkor.ontime`. Duplicate
-build numbers fail during the Google Play upload step.
+Keep `pubspec.yaml` as the source of truth for the manually managed public
+version name, such as `version: 1.0.0+1`. Android CI ignores the checked-in
+build suffix for Play uploads, so do not open PRs only to bump `+2`, `+3`, and
+similar build numbers. The generated `github.run_number` must still be greater
+than every previously uploaded Google Play build for `club.devkor.ontime`;
+duplicate or lower build numbers fail during the Google Play upload step.
 
 ## Local Release Build
 
@@ -49,7 +62,11 @@ Create the release source-set config before building:
 ```sh
 mkdir -p android/app/src/release
 base64 --decode android-google-services.json.b64 > android/app/src/release/google-services.json
-flutter build appbundle --release --dart-define=REST_API_URL=<api-url>
+flutter build appbundle --release \
+  --build-name=<version name from pubspec.yaml> \
+  --build-number=<monotonic Android versionCode> \
+  --dart-define=ENV=prod \
+  --dart-define=REST_API_URL=<api-url>
 ```
 
 On macOS, use `base64 -D` instead of `base64 --decode`.

docs/Android-Release-Signing.md

@@ -49,7 +49,9 @@ export ANDROID_KEYSTORE_PASSWORD=<keystore-password>
 export ANDROID_KEY_ALIAS=<release-key-alias>
 export ANDROID_KEY_PASSWORD=<release-key-password>
 
-flutter build appbundle --release
+flutter build appbundle --release \
+  --build-name=<version name from pubspec.yaml> \
+  --build-number=<monotonic Android versionCode>
 ```
 
 ## How Validation Works

docs/Android-Signing-Setup.md

@@ -82,7 +82,9 @@ and exports `ANDROID_KEYSTORE_PATH` to that temporary file. Do not create
 Google Play prefers Android App Bundles:
 
 ```sh
-flutter build appbundle --release
+flutter build appbundle --release \
+  --build-name=<version name from pubspec.yaml> \
+  --build-number=<monotonic Android versionCode>
 ```
 
 For APK validation outside Play:
@@ -120,8 +122,12 @@ Run these checks before handing a release build to QA or Play Console:
 ```sh
 flutter analyze
 flutter test
-flutter build appbundle --release
+flutter build appbundle --release \
+  --build-name=<version name from pubspec.yaml> \
+  --build-number=<monotonic Android versionCode>
 ```
 
-Confirm that `pubspec.yaml` has the intended `version` and that the build number
-is greater than every previous Play Console upload for `club.devkor.ontime`.
+Confirm that `pubspec.yaml` has the intended public version name. In GitHub
+Actions deploys, Android `versionCode` comes from `github.run_number`; for any
+manual Play upload, provide a build number greater than every previous Play
+Console upload for `club.devkor.ontime`.