Ease of Installation, Setup, Build, and Automation

From wiki.gpii
Jump to: navigation, search

The following is a set of notes compiled after the experience of merging the GPII-1318 "big branches," which finally bring the GPII system into a relatively up-to-date form with third-party dependencies, especially Node.js 4.x.

Make it easier to build and run the GPII on a developer system

  • Precise, step-by-step instructions within the top-level README of each project, describing how to:
    • Obtain all necessary base dependencies to run the code, e.g.
      • Node.js and npm
      • Native node module build toolchain:
        • Visual Studio build tools or XCode command line tools or gcc and related dependencies
        • Python
      • Hot fixes, patches, or libraries that are crucial for ensuring the system actually works properly
    • Install all requisite dependencies
    • Build the code
    • Run all unit and acceptance tests
  • A script that reliably does the above steps in a way that is 100% consistent with our continuous integration infrastructure, which can be run:
    • On a developer's local machine
    • Manually within a bespoke virtual machine (e.g. one that a developer manually set up in VMWare)
    • Completely automatically within a Vagrant virtual machine
  • The resulting system should resemble, to a reasonable degree for an in-development project, the same experience that an end user should have with the GPII
    • i.e. no "lore," "gotchas" conditional requirements, manually sourced dependencies, etc.
    • Doesn't, you know, leave their system in a chaotic state with high contrast mode permanently enabled
  • Requires a reasonably minimal number of steps to get a working GPII system

Make it easier to test the GPII in various configurations on a developer's system

  • Single-line, consistent, easy-to-remember commands to run each and all tests:
    • On a developer's local system
    • In an automatically-provisioned Vagrant box
  • Whole-system integration tests that will automatically:
    • Build all docker containers for hosted "cloud infrastructure" such as the Preferences Server, Cloud-based Flow Manager, Authorization Manager, etc.
    • Provision Vagrant boxes for local and cloud infrastructure using a configuration that allows them to communicate with each other
    • Run all integration tests associated with the GPII, allowing developers to verify that their changes work in an environment that is essentially identical to our hosted infrastructure.
  • Clear instructions on all required AT dependencies to run the acceptance tests, and where to source them:
    • e.g. JAWS, NVDA, etc.
  • A script that automatically installs all of these dependencies that can be reliably obtained via a package manager (Chocoloatey on Windows), and a profile of the acceptance tests that is intended to work with the subset of ATs that can installed automatically in this way

Provide reliable, trustworthy automated continuous integration that tells developers when their code is broken

  • The results of all builds and test runs should be posted publicly to an always-available website and posted to a mailing list which all committers are required to subscribe to
  • Github web hooks should always be registered for the continuous integrate server to ensure that CI runs after every push
  • Developers can run on their local machines, with a single command, the same process that is run by the continuous integration server, which:
  • Is run and maintained on, at minimum, the latest supported GPII operating system (e.g. Windows 10)
  • Developers understand how it works, and feel a commitment to ensuring that the build never breaks
  • A tutorial is available that describes to project developers:
    • How our continuous integration system works
    • Which configuration files and tools are needed to run the CI and test automation
    • Where to go to see the results of the builds
    • Plans and next steps for the Quality Infrastructure, particularly related to:
      • Improved UIs for looking at the results of builds
      • Automatic QI and testing for all pull requests
      • Support for multiple versions of VMs (for testing across different operating systems versions, for examples)

Dependencies between GPII modules should be sufficiently configurable as to enable major upgrades in one module to not cause the others to break

  • i.e. managed using "idiomatic" techniques such as Node package.json files and versioned releases (including development releases), not manual scripts that cause tight-coupling between repositories where, say, the linux or windows repositories break due to changes being pushed into universal

New third-party assistive technology can be integrated into the system without having to maintain separate, LGS-style forks of key configuration files

A variety of preferences can be saved to the GPII by a preferences editor such as the First Discovery Tool, and be enacted by the GPII without requiring arcane or undocumented configuration file changes