HowToAddNewTransitAgencyModule - mtransitapps/mtransit-for-android GitHub Wiki

How to add new transit agency module (WIP) ➕🆕

Git repository setup

Pick project directory ID:

2 letter country code + location + agency name + transport mode (xx-location-transit-agency-bus)

Template repository: https://github.com/mtransitapps/xx-location-transit-agency-type-android

gh repo create mtransitapps/xx-location-transit-agency-bus-android --disable-wiki --public --template mtransitapps/xx-location-transit-agency-type-android --clone

(Alternative: use an existing module repository as a starting point)
Create new git repository https://github.com/mtransitapps/xx-location-transit-agency-bus-android with default branch master (default for mtransitapps org) and a README & LICENSE to have 1 commit on the default branch (gh repo create)

gh repo create mtransitapps/xx-location-transit-agency-bus-android --disable-wiki --public --add-readme --license=apache-2.0 --clone

Agency config setup

in /config directory:
- agency_name: all valid agency names (short -> long)
- cities: static list of cities deserved by the agency
- input_url: GTFS static url
- input_url_next: (optional) another GTFS static url for future schedule
- parent_agency_name: (optional) all valid parent agency names (short -> long)
- parent_agency_color: (optional) the parent agency color
- pkg: package name for Play Store like org.mtransit.android.ca_location_transit_agency_bus
- source_url: web page URL where the GTFS static feed is shared
- state: (optional) state/territories/provinces names (short -> long)
- gtfs:
  - agency.json: JSON file containing agency settings (source)
    - target_route_type_id: (required) route type integer from GTFS Static routes.route_type
    - default_color: (required) default color if not extracted from routes colors
    - ...
  - route.json: JSON file containing route settings (source)
    - ...
  - (only set values when different from default)
  - (to add comments to the JSON config related to a field: append _comment the field name like field_name_comment for comments about field_name)
- lang: (optional) language code for the agency (default: en)
  - fr: file presence indicate that agency supports french language
- store:
  - internal: empty file presence indicating to automation that this module is available in Internal channel
in /app-android directory:
- src/main/res/values/
  - route/direction/stop agencies: #GTFS
    - gtfs_rts_values.xml: GTFS static settings (source)
      - gtfs_rts_db_version: integer that will be automatically overwritten (0)
      - gtfs_rts_contact_us[_fr]: string with the URL of the contact us web page
      - gtfs_rts_fares[_fr]: string with the URL of the fares web page
    - gtfs_real_time_values.xml: GTFS Real-Time settings (source)
    - next_bus_values.xml: Next Bus settings (source)
  - bikes agencies: #GBFS
    - bike_station_values.xml: GBFS settings (source)
  - common:
    - rss_values.xml: RSS news settings (source)
    - twitter_values.xml: Twitter/X news settings (source)
    - youtube_values.xml: YouTube news settings (source)
- src/play/listings/
  - generate images with:
```
gh workflow run mt-image-gen.yml --ref $(git rev-parse --abbrev-ref HEAD) -f commitDirectly=true
```

Initial pull request

Init repo with code_setup.sh from commons repo in another directory (needed for CI workflows)

../other_directory/commons/code_setup.sh

verify generated files (git submodules...) and stage all current changes with git add .
(RDS agencies only) <- this should be done automatically when opening the PR
- download input data with ./download_only.sh
- prepare downloaded input data with ./prepare_only.sh
- parse current data with ./parse_current.sh
- verify and stage all new changes with with git add .
Create "setup" branch with git switch -C setup
Commit and push staged changes with git commit -m "Setup" && git push
Open pull request for this branch with gh pr create --draft --assignee "@me" --fill-first
((?) Create app screenshots now)

gh workflow run mt-record-screenshots.yml --ref $(git rev-parse --abbrev-ref HEAD) -f buildFromSource=true

Once PR looks good✨, it can be merged🔀.

Add to DEV build status dashboard data/modules.json in mtransitapps.github.io

Play Store setup

(need Play Store console access)

Create new app on Play Store console
- App name: from /app-android/src/main/play/listings/en-US/title.txt
- Package name: from /config/pkg
- Default language: English (United States) (default)
- App or game: 🔘 App
- Free or paid: 🔘 Free
- You'll get automatic protection: Turn off (do NOT want to prevent unauthorized redistribution outside of Play Store)
- Declarations: ☑️ Developer Program Policies & ☑️ US export laws

Grow users > Store presence
- Store listings

gh workflow run mt-store-listing-push.yml --ref $(git rev-parse --abbrev-ref HEAD) -f allowNonDefault=true

Store settings
- Category: Maps & Navigation
- Tags: Bus(?), Public transport, Train(?), Travel & local
Monitor and improve
- Policy and programs > App content
  - Advertising ID > 🔘 No
  - Ads > 🔘 No, my app does not contain ads
  - App access > 🔘 All functionality in my app is available without any access restrictions
  - Content ratings
    - Email address, All Other App Types, ☑️ I agree... IARC
    - 🔘 No for all questions.
  - Data safety
    - Data collection and security > 🔘 No
  - Financial features > 🔘 My app doesn't provide any financial features
  - Government apps-> 🔘 No
  - Health apps > 🔘 My app does not have any health features
  - Target audience and content > ☑️ 18 and over
  - Privacy Policy:
```
https://mtransitapps.github.io/privacy
```
Test and release
- Advanced settings
  - Inline Installs > ☑️ Enable Inline Installs
- Production
  - 🗺️ Countries/regions: target All countries/regions
- Testing
  - Closed testing: (optional, only if not intended for immediate Production release)
    - Create track with name:
```
Beta (Private)
```
    - Testers:
      - 🔘 Google Groups:
        [email protected]
      - Feedback URL:
        https://groups.google.com/g/montransit-beta
  - Internal testing
    - Testers:
      - 🔘 Email lists: ☑️MonTransit Team
      - Click on 🔗Copy link to get the testing URL
    - Create new release
      - IMPORTANT ⚠️ > Change signing key 🔐 > Confirm:
        
        Use the same key as another app in this developer account > select any app
        
        ☑️ Confirm change key is set in Protected with Play > App signing (.../keymanagement in URL)
        
        App signing key certificate
        
        MD5 certificate fingerprint: 6C:73...F0:D9
        
        SHA-1 certificate fingerprint: EE:6B...F6:39
        
        SHA-256 certificate fingerprint: F8:EA...DA:7A
        
        Upload key certificate
        
        MD5 certificate fingerprint: 51:ED...43:BE
        
        SHA-1 certificate fingerprint: B7:86...75:52
        
        SHA-256 certificate fingerprint: 60:3D...B4:3B
      - Use workflow to publish release to Internal
```
gh workflow run mt-release.yml --ref $(git rev-parse --abbrev-ref HEAD) -f allowNonDefault=true
```
      - ⬇️Install & 🧪test the app quickly

Production release

Publish in Production on the Play Store:
Test and release > Latest releases and bundles
- Select the Internal track
- Click on Promote release -> Production
- Click on Next then Save
Publishing overview
- Sent X changes for review

WAIT 🔄 until Production channel is published.

Post production release tasks

Use mt-store-channels.yml to enable automatic app updates in Production channel
Update data/modules.json in mtransitapps.github.io to set "store": "production" for the agency module.

Update wiki/Apps

`Setup` issue template

xx-location-transit-agency-type-android/ISSUE_TEMPLATE/module-setup.yml

- [ ] Created initial `Setup` PR with agency module configuration [ℹ️](https://github.com/mtransitapps/mtransit-for-android/wiki/HowToAddNewTransitAgencyModule#agency-config-setup)
- [ ] [Generated screenshots](../actions/workflows/mt-record-screenshots.yml) _during service hours_
- [ ] [Generated images](../actions/workflows/mt-image-gen.yml)
- [ ] [Created initial Store listing](https://play.google.com/console/developers/create-new-app) [ℹ️](https://github.com/mtransitapps/mtransit-for-android/wiki/HowToAddNewTransitAgencyModule#play-store-setup)
- [ ] Added agency module to [mtransitapps.github.io/data/modules.json](https://github.com/mtransitapps/mtransitapps.github.io/blob/master/data/modules.json)
- [ ] [Published to store `Internal` channel](https://play.google.com/console/)
- [ ] [Published to store `Production` or `Beta (Private)` channel](https://play.google.com/console/)
- [ ] [Enabled store `Production` or `Beta (Private)` channel](../actions/workflows/mt-store-channels.yml) for the repo.
- [ ] Updated agency module `"store"` to `"production"` or `"beta-private"` to [mtransitapps.github.io/data/modules.json](https://github.com/mtransitapps/mtransitapps.github.io/blob/master/data/modules.json)
- [ ] Updated [wiki/Apps](https://github.com/mtransitapps/mtransit-for-android/wiki/Apps) or [wiki/BETA](https://github.com/mtransitapps/mtransit-for-android/wiki/BETA)

[More info](https://github.com/mtransitapps/mtransit-for-android/wiki/HowToAddNewTransitAgencyModule)

Agencies data sources

HowToAddNewTransitAgencyModule - mtransitapps/mtransit-for-android GitHub Wiki

How to add new transit agency module (WIP) ➕🆕

Git repository setup

Agency config setup

Initial pull request

Play Store setup

Production release

Post production release tasks

Setup issue template

Related

`Setup` issue template