Development guide - fmidev/weather-app GitHub Wiki

Purpose of this page is to help developers from international forks to get started with the project. Any international fork related settings should be added into that fork's own wiki-page.

Requirements

  • iOS development requires Mac + Xcode as well as Developer -role in App Store’s organisation so Xcode can download required certificates
  • Android development doesn’t have specific requirements
  • Preferred or required software: Android Studio, Visual Studio Code, Xcode

Source code

  • International versio is a fork from FMI Weather app
  • Updates are only done from FMI -version to Intl version. No changes come from Intl version to FMI -version.
  • Deploy to App Store and Play Store is done by Github Actions

Setting up development environment

  • Clone source code from repository
  • Install all necessary applications etc, see project’s readme for more information
  • iOS development requires steps mentioned in Requirements -section
  • insert all required information to .env
    • most likely only Google Maps API-KEY (can be found from Here)
    • .env file should NEVER be saved to version control
  • insert all required information to defaultConfig
    • more information about each setting can be found from project’s Github wiki-page and FMI version’s wiki-page
    • defaultConfig should NEVER be saved to version control
    • changes to defaultConfig NEED to be updated to Github Actions' environmental variables
      • Settings -> Secrets and variables -> Actions, update DEFAULTCONFIG's value (you won't be able to see the value, only update it)
      • Github Actions deploy to stores will read values from DEFAULTCONFIG environmental variable

Preparing for deployment to App Store and Play Store

  • Create release-YYYY-MM-DD -branch from main
  • Update version number to package.json (use semantic versioning)
  • Commit and push all changes to release-YYYY-MM-DD -branch

Deploying application from Github to App Store and Play Store

  • Go to Actions -page and select CI / CD -workflow
  • Select Run workflow
    • Select branch to deploy (release-YYYY-MM-DD)
    • Select platform (best practice is to select either iOS or Android)
    • Set increment build and version number to true (without this build number will not be updated and stores will reject deployment)
  • Run workflow
  • Now run workflow for the second platform with same settings
  • After both workflows are done, create a pull request from release-YYYY-MM-DD to main and merge it to main -branch
  • Go to App Store Connect and Google Play Console to check that new version is available

Testing

App Store

  • App Store Connect is used to deploy iOS application
  • Go to Testflight -tab and you should see the new version there
  • Those users who are registered in Testflight will get notification about new version automatically

Google Play

  • Google Play Console is used to deploy Android application
  • There are three different testing tracks you can use: internal, closed and open
  • Internal track is for developers and testers and doesn't require review - use that one for testing
  • Create new release to internal track and select testers
  • Publish release
  • Sooner or later new version is available for testers

Apple Developer account

Apple's certificates and provisioning profiles are valid for one year. After that, you need to renew them and update them to Github Actions' secrets and variables.

Requirements

  • Provisioning profile needs a valid certificate to work.
  • Certificate needs a Certificate Signing Request (CSR) file.
  • CSR needs a Mac

Creating a new Certificate Signing Request (CSR)

  • CSR can be created from Mac's Keychain Access -app.
    • Open Keychain Access
    • Go to Keychain Access -> Certificate Assistant -> Request a Certificate from a Certificate Authority
    • Fill in your email and name
    • Save the file to your computer

Renewing new Certificate

  • Go to Apple Developer account (https://developer.apple.com/account/)
  • Go to Certificates, Identifiers & Profiles -page
  • Go to Certificates -page
  • Create new Certificate (valid certificate for the Provisioning Profile)
    • Select iOS Distribution (App Store and Ad Hoc)
    • Upload CSR file you created earlier
    • Download the certificate and save it to your computer
  • Open the certificate (double click) and it will be saved your to Keychain
  • Export the certificate from Keychain
    • Open Keychain Access
    • Find the certificate
    • Right click and select Export
    • Save the file to your computer as .p12 -file (no password)
  • base64 encode the .p12 -file
    • openssl base64 -in certificate.p12 -out certificate_base64.p12.base64
  • copy its contents to clipboard
    • cat certificate_base64.p12.base64 | pbcopy
  • paste it to Github Actions' secrets and variables (IOS_DIST_SIGNIN_KEY)

Renewing Provisioning Profile

  • Go to Apple Developer account (https://developer.apple.com/account/)
  • Go to Certificates, Identifiers & Profiles -page
  • Go to Provisioning Profiles -page
  • Create new Provisioning Profile
    • Select Distribution / App Store Connect
    • Select the App ID
    • Select the certificate you created earlier
    • Name the profile (unique name makes life easier)
  • No need to download the profile
  • Update the profile's name to Github Actions' secrets and variables (IOS_PROVISIONINGPROFILE_NAME)

Github Actions

There are currently two pipelines in Github actions

CI / CD

Used to build and deploy release bundles to Testflight and Google Play. It is usually run from release-branch manually.

Pipeline source code can be found from .github/workflows/main.yml. It uses Fastlane for build and deploy.

The latest Android build from main-branch

Generates the latest APK from main branch for testing. Updated every time when there is push to main-branch. The APK can be downloaded from Artifacts section from each run, unzipped and installed with command adb install latest.apk to test device.

Pipeline source code can be found from .github/workflows/latest.yml. It uses Fastlane for build.

Fastlane

Github Actions pipelines use Fastlane for build and deploy https://fastlane.tools/. You can install it locally on MacOS device with brew

brew install fastlane

Fastlane commands (lanes) for Android are defined in android/fastlane/Fastfile, for iOS there is corresponding ios/fastlane/Fastfile. You can test lanes locally with

fastlane android|ios [lane]

if you first define environment variables that command depends.

Mockserver

You can test locally warnings and announcements with mockserver, because live warnings and announcements are not always available.

Git clone the whole repo or checkout main directory and mockserver only if you just need mockserver

git clone --no-checkout https://github.com/fmidev/weather-app
cd weather-app
git sparse-checkout init --cone
git sparse-checkout set . mockserver
git checkout

Install yarn if not already installed

npm install --global yarn

Install packages

yarn install

Start mockserver with command

yarn server

or

yarn server:watch

if you develop mockserver/server.mjs script. In this case install also nodemon with npm install -g nodemon.

The script prints IP addresses where server is running. The address with numeric IP works in local network and is usually better for development. Change defaultConfig.ts or widgetConfig.json to use following urls (or numeric IP ones)

Warnings url

http://localhost:3000/warnings

Announcements url

http://localhost:3000/mobileannouncements

Timeseries url

http://localhost:3000/timeseries

Supports forecast, observations and geolocation only in the format that the app uses.

Setup (HTTP PUT)

http://localhost:3000/setup/geolocation/:location for changing location. Location can be tikkurila|newyork|singapore.
http://localhost:3000/setup/forecast/:season for changing summer/winter forecast
http://localhost:3000/setup/warning/:type for changing warnings. Type can be none|land|sea|wind.
http://localhost:3000/setup/datamode/:mode for changing how timesteps are converted. Mode can be constant or dynamic (default).
http://localhost:3000/setup/announcement/:announcement for changing announcement. Announcement can be none|crisis|maintenance.
http://localhost:3000/setup/debug/:boolean for debug mode on/off. Debug mode prints requests to console.

Misc GET endpoints

http://localhost:3000/count request count
http://localhost:3000/config outputs DynamicConfig
http://localhost:3000/setup outputs current server settings
http://localhost:3000/quit quits the server
http://localhost:3000/error

You can use normal browser for GET queries, CURL in command line for GET/PUT and REST client like Insomnia in desktop environment.

Using mock server with Android test build

You can use mockserver with Android test build by giving config-endpoint as launch parameter for adb

adb shell am start --es config 'http://localhost:3000/config' -S -D fi.fmi.mobileweather/.MainActivity

Same in Appium configuration would be

capabilities: {
  optionalIntentArguments: `--es config 'http://localhost:3000/config'`, // Android
  processArguments: {args : ['-config', 'http://localhost:3000/config']}, // iOS
}

Disclaimer

  • Updates can and will be merged from FMI -version to international versions so any major changes to forked International project can be breaking changes and prevent merging new changes from FMI -version.