Skip to content

01_Flox Standard Workflow

Jump to bottom
thommann edited this page Feb 22, 2023 · 13 revisions

Development Workflow

Introduction

Flox includes two workflows: The standard workflow that is intended to be used on larger projects, and the mini workflow for small, lean projects that (usually) don't include a PM. This Page is about the standard workflow; see 2_Flox Mini Workflow for the minimal version. The GitHub actions that are set up within Flox by default correspond to the standard workflow.

Main Workflow

It is highly recommended to use the following specified workflow for the development of new Flox projects. The following diagram outlines the basic workflows for ensuring the delivery of high-quality content through comprehensive testing and validation: flox-Workflows drawio

This workflow assumes the existence of three long-lived systems: dev, test and live.

  • dev continuously mirrors the state of development, including all features that have been developed, but not yet validated. This system is accessed by developers and PMs.
  • test is a subset of these features, and includes all those that have gone through staging, and passed PM review. This system is accessed by customers!
  • live is a subset of the test features, and includes only those that have gone through an additional customer review. Additionally, releases to the live system are only done upon customer request. This system is accessed by customers and end users!

The primary idea behind this workflow is that initially, new features (or the code thereof) are reviewed by developers. The features are then tested by a PM, before being given to a customer for testing. Only after achieving customer approval, a feature can be merged into the live/production system. This process therefore involves all stakeholders at some point, ensuring a feature is properly implemented, and works as intended for the end user.

Initial infrastructure spin-up

The infrastructure of these three long-lived systems must initially be spun up manually. Using the manually triggered GitHub action Set up AWS infrastructure, each of these systems can be started. The system type (live, test and dev) can be chosen upon running the action. If you are starting up a customer-facing system (either test or `live), you must set the checkmark for "Force deployment", as well as enter "confirm" in the text box below. This is to ensure that no customer-facing systems can be changed on accident.

Additionally, the startup script checks whether the given distribution is already online; therefore, if you are trying to start up the dev system when it's already online, the action will fail unless the "Force deployment" checkmark is set.

There are some (rare) occasions where redeploying a system in this manner can be necessary; however, you must be aware that changing e.g. the Cognito or Database configuration within Terraform can lead to the loss of real, customer-facing data. Therefore, this action should be used as rarely as possible, and with great care.

For pure code updates (as opposed to infrastructure), no manual action is needed; more on the related workflows below.

The dev System

Whenever a Pull Request is merged into the dev branch, the dev system, assuming it has been spun up previously, will be updated through an automatic GitHub action (update-dev.yml). Therefore, the dev AWS deployment system should always mirror the current state of the development branch.

If, for some reason, the dev system has not been spun up yet, or is not running, the corresponding update action will fail with the message "Deployment in mode 'dev' is not online at URL: ...". Note that this online status check only checks whether the website (and thus the frontend) is reachable. This also applies to other update workflows: They first check whether the given system is online, as it being offline can lead to undefined behavior within the update scripts that trigger Terraform runs.

Staging Process

The principle behind the staging process is to collect a number of features from dev, instantiate a staging environment, and allow PMs to validate whether those features fulfill the given deliverables. The staging workflow follows the following sequence:

  1. The staging process is initiated by creating a stage branch from the dev branch, using the manual stage-from-dev GitHub action. This will set up a staging environment with a name such as stage-16-08-2022-09-24, corresponding to the branch's creation time.
  2. The assigned PM can then begin validating the features and, upon completion, the automatically created PR to master can be accepted.
  3. If any fixes are needed beforehand, developers can create a branch prefixed fix- and merge it into the staging branch through a pull request.
  4. Once PM acceptance is achieved, the stage-x branch's automatically opened PR can be merged into master, meaning the features are ready for customer-facing tests. This will automatically spin down the staging system and delete the corresponding Terraform workspaces.

Releasing for Customer Testing & Production

After the master branch has been updated, the features can be released for customer testing on the test system. This is achieved as follows:

  1. Create a draft release by manually triggering the Stage 3: Manually Tag a branch as release GitHub action on the master branch. Enter a valid version number according to the action's input prompt.
  2. GitHub Actions will now automatically create a new release tag and update the test system. Ensure the features work as intended and get customer approval for creating a new release. A new release may (but usually won't) lead to some downtime!
  3. Production release is then achieved by marking the draft release as released (from "Tags" on the repository's start page -> "Create Release from Tag"). The rest of the process is automated; GitHub Actions will update the live system based on the new release, and add the .zip files for frontend and backend to the release as build artifacts.
Clone this wiki locally