Development Process Guide

Related documents

• User Interface Style Guide
• Directory Layout
• Scripts Reference
• Coding Style Guide
• Testapp

Table of contents

• Technology use
• Project dependencies
• WebApps
  • The Service Worker and caching
• Native apps
• Building apps
• Graphics
  • Aircraft top view image
  • App store images
• Building the airport database
• Common infrastructure testing
• Testing and debugging apps
  • Unit tests
  • Testapp
  • Feedback and Trouble reports
• Building the documentation

Technology use

In general, POH Performance apps use the following criteria for client-side technology:

• The technology must be deployed in iOS Safari, Chrome, and Android WebViews for at least 5 years.
  and/or
• The technology should be ≥ 95% usage in caniuse.com.
  These criteria apply to JavaScript, HTML, and CSS features.

Server-side technology is only limited by server capabilities. The server is currently hosted on a Godaddy.com Web Hosting Plus shared host. The server is preconfigured to use Apache as the server framework and does not support NodeJS.

Project dependencies

The NodeJS scripts require some node libraries to be installed. See the Scripts Reference.

The app development and deployment process may rely on the following software:

• Adobe Photoshop
  While not required for new apps, many of the images for the existing apps were developed using Photoshop. The .psd files are recorded in the source/image/<appName>/ directories. Typically, an aircraft top-view is derived from a top-view image in a POH and then edited in Photoshop. The top-view image is displayed on the takeoff and landing runway diagrams. The top-view image and a favicon are the only images required for a Web-only deployment.
• Android Studio
  Android Studio is required to generate Android images. The simulator is also typically used to generate app snapshots for the app store. However, it is not required for a Web-only deployment.
• Cordova
  Apache Cordova generates native Android and iOS apps. It is not required for a Web-only deployment.
• Xcode
  Xcode is required to generate, sign, and submit iOS images. The iOS simulator is also typically used to generate app snapshots for the app store. However, it is not required for a Web-only deployment.

WebApps

All clients are fundamentally WebApps. They may be deployed on desktop devices, but they may also be used on mobile devices for personal use outside of the app store distribution. The WebApp is a Progressive WebApp (PWA) that may be installed on a mobile device's homepage and can operate while disconnected from the internet after being installed or loaded.

The Service Worker and caching

The WebApp also contains a Service Worker that caches app source files but forwards server API requests to the network when connected. The WebApp build process inserts a manifest of all files (other than the Service Worker) into the index.html file. When connected, the index.html file is always fetched from the server, bypassing local or network caching. The Service Worker will preload all files in the manifest into the application cache whenever a different index.html file is fetched from the server.

The files in the manifest have a unique element in the path name for each build. This ensures that only the files associated with the current version of the index.html file will be placed in the cache. Any caching in the client or network will be ignored.

Native apps

The build process uses Apache Cordova to build native iOS and Android apps from WebApps. The WebApp Service Worker is disabled when using Cordova to avoid violating app store policies against loading code.

Building apps

The build process is run by a main Makefile in the project root directory. It has the following targets:

• build
  Build both cdv and web targets. This is the default target.
• cdv
  Build a Cordova source image of all apps. The results are placed in build/cdv. The images can be imported into a Cordova project.
• checkMdLinks
  Checks that all the Runs checkMdLinks.js on all Markdown files in doc/.
• clean
  Removes the build/ directory
• clobber
  Makes both the clean and imageClean targets.
• db
  Build an airport database for all apps with airport databases.
• doc
  Build a complete set of documentation from the Markdown and other files in source/doc into HTML files in build/doc.
• docClean
  Removes the files in build/doc.
• image
  Generates the Cordova and web images for each app.
• imageClean
  Removes the generated Cordova and web images.
• lineCount
  Builds a source line count of each app and the common code.
• lint
  Lints (eslint) all apps. The individual lint output in each file is sent to a file in build/lint so that only changed files are re-linted.
• lintClean
  Removes the files in build/line so that all files will be re-linted the next time lint is made.
• serve
  Run a web server from build/web. Listens for change in source/app and runs lint. If the lint produces output, then the web page for the app displays the lint output. Otherwise, the server displays the newly built web images.
• web
  Build a web server image of all apps. The results are placed in build/web. The images can be directly transferred to a web server.

The root Makefile invokes sub-makefiles for targets that build for all apps. If a sub-makefile of the form <appId>.mk exists, it will use that to build the target. Otherwise, it will use app.mk.

Graphics

The icons, favicons, and splash screens are all automatically generated. See Icon and splash screen generation. The splash screens may contain an optional logo image which must be generated by hand.

Aircraft top view image

The aircraft apps require an aircraft top view image to use on the takeoff and landing runway diagrams, which is also used on the splash screens. This is typically cropped from the POH or other sources and adjusted for clarity using tools like Photoshop.

App store images

The app store icons are typically generated using the icon generation scripts. App images for the app stores are normally taken by running device simulators for different-sized devices in Xcode and Android Studio.

Building the airport database

Apps that require an airport database must be added to the aircraftApps in the main Makefile. This will ensure that databases for them will be built.

The airport database is built by combining the airport data from the NFDC and ourairports.com. See the Airport Database Reference. The bulk of the work is done using the buildAirportDB.js script.

The database is built by running make db in the project root directory. Prior to building the database, you must download the current version of the NFDC airport and runway data in the Legacy format APT.txt file to the source/airportData/NFDC/ directory. When make db is run, it does the following:

• Downloads the airports.csv and runway.csv files from ourairports.com to the source/airportData/ourairportscom/ directory.
• Downloads the stations.cache.xml.gz file and unzips it to source/airportData/stations.xml.
• For each app that requires a database:
  • Finds the source/airportData/dbFlags/<appId>.txt file containing this app's unique flags.
  • Runs scripts/buildAirportDB.js passing the retrieved flags and directing the log output to source/airportData/logs/<appId>_log.txt

Use the source/airportData/dbFlags/<appId>.txt to specify the runway requirements that are unique to the aircraft. For example, to ensure that the included runways are long enough for any aircraft of that type to takeoff or land even under the best conditions. The log files are useful for answering questions about why a conflicting code was dropped or why an airport was dropped because it did not have runways compatible with the aircraft.

Common infrastructure testing

The Testapp is a standalone app designed to help test and debug MVCS and other infrastructure code. It runs unit tests and has pages to exersize various common functions.

Testing and debugging apps

Almost all testing and debugging use the WebApp form of an app. Running make serve builds the app and starts a web server on https://localhost:8000 that you can open with a browser and navigate to the app of interest. Use the browser's debugger as required. The makefile will automatically rebuild the app when the source is updated. You will have to refresh the browser to see the updated results.

The Settings page has a hidden card for developers. You can view the card by entering XYZZY (look it up) in the password field. The card contains the following:

• An app Test button that opens the Test page and runs any built-in unit tests.
• A JSON dump button that will mail the app state to the email address on the Settings page.
• A JSON restore button presents a dialog that allows you to paste edited JSON to use to restore the app state.
• A checkbox that allows you to disable saving both locally and to the server.
• A Load button to allow you to load a trouble report into the app

Unit tests

Most apps have built-in unit tests. Pressing the Test button in the Settings page developer card will open the Test page and run all built-in unit tests. Tests are defined using unitTest. Aircraft apps typically have the following tests:

• The Aircraft page sets up a generic scenario and then sequentially sets up the current aircraft for each available internal model and checks that there are no invalid inputs or outputs on any page.
• Each performance calculating page (e.g., Departure, Enroute, Destination, etc.) sets up one or more scenarios and tests that the page outputs are correct.
• Each defined aircraft model tests that the model compute methods generate the correct result for all phases of flight. Often, these tests use example calculations from the aircraft performance section for the POH or OM. Keep in mind that these examples are sometimes wrong, and the data in the performance section is authoritative.
• Each defined aircraft option tests that the model compute methods generate the correct result for all phases of flight with the option installed. It may also test that other options are correctly excluded when this option is installed or that any prerequisite options must be installed before this option can be enabled.

The test page will display failed test result. Selecting Show detailed results will display all results, both passed and failed.

Testapp

The Testapp is an internal WebApp specifically for testing the MVCS infrastructure. It contains pages that test UI elements, the infrastructure for common pages, and infrastructure unit tests.

Feedback and Trouble reports

Users can press the Email button in the Settings page "Questions or feedback" row to send email to the webmaster at info@pohperformance.com using their local email app.

Users may also file a Trouble Report (TR) by pressing the Send button on the "Trouble report" row. Trouble reports record all app state variables at the time of the report and include a user message. Each TR has an ID string that begins with "TR-". The ID contains some random digits that would make it difficult to guess. The reports are stored on the server and a notification is sent to the webmaster at info@pohperformance.com. A reminder notification is sent daily until the TR is archived.

A TR may be retrieved by pressing the Trouble Report "Load" button and entering the Trouble Report ID. This will set the app's input state variables according to the TR data allowing you to see the user's exact setup. Once the problem is determined, the TR can be archived by pressing the Trouble Report "Archive" button.

XXX use browser-sync and the php built in server.

Building the documentation

XXX