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 + city/area name + agency name + transport mode (ca-city-transit-agency-bus)

(Alternative: use an existing module repo code as a template/starting point)
Create new git repository https://github.com/mtransitapps/ca-city-transit-agency-bus-android with default branch master (default for mtransitapps org) and a README or LICENSE to have 1 commit on the default branch or use git commit --allow-empty -m "First commit" & git push after cloning (gh repo create)

gh repo create mtransitapps/ca-city-transit-agency-bus-android --public --add-readme --license=apache-2.0 --clone

Agency config setup

in /config directory:
- agency_name: all valid agency names from short to 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 from short to long
- parent_agency_color: (optional) the parent agency color
- pkg: package name for Google Play Store like org.mtransit.android.ca_city_transit_agency_bus
- source_url: web page URL where the GTFS static feed is shared
- state: (optional) state/territories/provinces names from short to 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)
in /app-android directory:
- src/main/res/values/
  - route/direction/stop agencies:
    - 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:
    - bike_station_values.xml: GBFS settings (source)
  - common:
    - instagram_values.xml: Instagram news settings (source) (not working at the moment)
    - rss_values.xml: RSS news settings (source)
    - twitter_values.xml: Twitter/X news settings (source)
    - youtube_values.xml: YouTube news settings (source)

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
- parse next data with ./parse_next.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
((?) Create app screenshots now)
Once PR looks good, it can be merged.

(?) Can trigger mt-release.yml workflow to generate 1st AAB.
Add to DEV build status dashboard dev/build-status/index.html in mtransitapps.github.io
Update ISSUE_TEMPLATE/modules-list.md

Play Store setup

(need Play Store console access)

Create new app on Play Store console

Grow users > Store presence
- Store listings
  - Create default store listing: use texts & images from /app-android/src/main/play/listings/
- Store settings
  - Category: Maps & Navigation
  - Tags: Bus(?), Maps & navigation, Public transport, Train(?), Travel & local
  - Email address: from /app-android/src/main/play/contact-email.txt
  - Website: from /app-android/src/main/play/contact-website.txt
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
- Production
  - Countries/regions: target All countries/regions
- Testing
  - Internal testing
    - Testers:
      - 🔘 Email lists: ☑️MonTransit Team
      - Click on Copy link to get the testing link
    - Create new release
      - IMPORTANT ⚠️ > Change signing key 🔐 > Confirm:
        
        Use the same key as another app in this developer account > select any app
      - Make an App bundle with (and Upload it.):
        gh workflow run mt-release.yml --ref $(git rev-parse --abbrev-ref HEAD) -f allowNonDefault=true -f skipPublishRelease=true
      - Release name should auto-fill (like: YY.MM.DDr0000)
      - Release notes should come from /app-android/src/main/play/release-notes/*/default.txt
      - NEXT > Save
Publishing overview
- Sent X changes for review

App screenshots

Use mt-record-screenshots.yml workflow (original):

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

Production release

Check if the Play Store listing looks good
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 add an empty /config/store/production file to enable automatic app updates in Production channel
Update main app discovery:
- add agency inside modules.json
- bump version modules_values.xml [module_db_version]
- (will be in next release, nice to have)
Update wiki/Apps

`Setup` issue template

- [ ] Created initial `Setup` PR with agency module configuration [ℹ️](https://github.com/mtransitapps/mtransit-for-android/wiki/HowToAddNewTransitAgencyModule#agency-config-setup)
- [ ] [Generated release AAB](../actions/workflows/mt-release.yml)
- [ ] [Created initial store listing](https://play.google.com/console/) [ℹ️](https://github.com/mtransitapps/mtransit-for-android/wiki/HowToAddNewTransitAgencyModule#play-store-setup)
- [ ] Updated [mtransitapps.github.io/dev/build-status](https://github.com/mtransitapps/mtransitapps.github.io/blob/master/dev/build-status/index.html)
- [ ] Updated [ISSUE_TEMPLATE/modules-list.md](https://github.com/mtransitapps/mtransit-for-android/blob/master/.github/ISSUE_TEMPLATE/modules-list.md)
- [ ] [Published to store `Internal` channel](https://play.google.com/console/)
- [ ] [Enabled store `Internal` channel](../actions/workflows/mt-store-channels.yml) for the repo
- [ ] [Generated screenshots](../actions/workflows/mt-record-screenshots.yml) _during service hours_
- [ ] [Published to store `Production` channel](https://play.google.com/console/)
- [ ] Updated [wiki/Apps](https://github.com/mtransitapps/mtransit-for-android/wiki/Apps)
- [ ] [Enabled store `Production` channel](../actions/workflows/mt-store-channels.yml) for the repo.
- [ ] Updated recommended [modules](https://github.com/mtransitapps/mtransit-for-android/blob/master/app-android/src/main/res/raw/modules.json) & [version](https://github.com/mtransitapps/mtransit-for-android/blob/master/app-android/src/main/res/values/modules_values.xml)

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

App screenshots

Production release

Post production release tasks

Setup issue template

Related

`Setup` issue template