From 9a895feefa270598376c5a1034f582ea07f5e770 Mon Sep 17 00:00:00 2001 From: Ed Davey Date: Tue, 8 Oct 2024 09:06:55 +0100 Subject: [PATCH 1/3] Docs: update README with info on running tests scripts --- README.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 9d8742ed..e5aa4150 100644 --- a/README.md +++ b/README.md @@ -4,19 +4,39 @@ This is a rebuild of the airTEXT.info service 1. [Getting started](/doc/getting-started.md) -## Static code analysis +## Tests -Run [Brakeman](https://brakemanscanner.org/) to highlight any security -vulnerabilities: +### Local unit and integration tests -```bash -$ brakeman +#### Fast feedback loop + +These tests (Rspec and Capybara) can be run at maximum speed with: + +```sh +bundle exec rspec ``` -To pipe the results to a file: +### Full pre-commit checks + +Before committing you should run our complete set of checks and tests. + +Choose from either the dockerised or undockerised version of the supplied +comprehensive test script which includes: + +- formatting files with `prettier` +- checking scripts with `shellcheck` +- linting Ruby files with `standardrb` +- linting JS with `eslint` +- linting CSS with `stylelint` +- running automated test suite with `rspec` +- running API specs and generating OpenAPI spec via the + `rswag_api_tests_with_docs` `rake` task +- analysing vulnerabilities in Ruby gems with `brakeman` + +e.g. -```bash -$ brakeman -o report.text +```sh +./script/no-docker/test ``` ## Making changes From 4fb2a071a52ea833abd6e00a43e83ccb1d7150c3 Mon Sep 17 00:00:00 2001 From: Ed Davey Date: Tue, 8 Oct 2024 09:09:55 +0100 Subject: [PATCH 2/3] Docs: Add info on location of deployed service --- README.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index e5aa4150..19ec5d3d 100644 --- a/README.md +++ b/README.md @@ -39,17 +39,6 @@ e.g. ./script/no-docker/test ``` -## Making changes - -When making a change, update the [changelog](CHANGELOG.md) using the -[Keep a Changelog 1.0.0](https://keepachangelog.com/en/1.0.0/) format. Pull -requests should not be merged before any relevant updates are made. - -## Releasing changes - -When making a new release, update the [changelog](CHANGELOG.md) in the release -pull request. - ## Architecture decision records We use ADRs to document architectural decisions that we make. They can be found @@ -81,9 +70,13 @@ To manage sensitive environment variables: ## Access -TODO: Where can people find the service and the different environments? +The service is deployed to Heroku at +[https://air-text-3e4548b53179.herokuapp.com/][]. ## Source This repository was bootstrapped from [dxw's `rails-template`](https://github.com/dxw/rails-template). + +[https://air-text-3e4548b53179.herokuapp.com/]: + https://air-text-3e4548b53179.herokuapp.com/ From a52e46bc92df5ce91eb06433aa19518f391afbcb Mon Sep 17 00:00:00 2001 From: Ed Davey Date: Tue, 8 Oct 2024 09:31:37 +0100 Subject: [PATCH 3/3] Docs: add notes on terminology --- README.md | 24 ++++++++++++++++++++++++ doc/terminology.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 doc/terminology.md diff --git a/README.md b/README.md index 19ec5d3d..e7fbeaae 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,29 @@ This is a rebuild of the airTEXT.info service 1. [Getting started](/doc/getting-started.md) +## Description of the service + +A service for providing forecasts and personalised alerts on air quality and +other environmental factors in: + +- Greater London +- Cambridge +- the Chelmsford/Colchester area + +## Terminology + +We aim to use and refine a "ubiquitous language" for use throughout the service. +We believe that this will optimise our communication and minimise our +misunderstandings and our cognitive load. We will aim use the same terms in: + +- the UI of the service +- the code we write +- our sketches and mockups +- our research sessions +- our documentation and our presentations to partner organisations + +See [./doc/terminology.md][] + ## Tests ### Local unit and integration tests @@ -80,3 +103,4 @@ This repository was bootstrapped from [https://air-text-3e4548b53179.herokuapp.com/]: https://air-text-3e4548b53179.herokuapp.com/ +[./doc/terminology.md]: ./doc/terminology.md diff --git a/doc/terminology.md b/doc/terminology.md new file mode 100644 index 00000000..1dad79f9 --- /dev/null +++ b/doc/terminology.md @@ -0,0 +1,46 @@ +# Terminology + +## Purpose + +We aim to use and refine a "ubiquitous language" for use throughout the service. +We believe that this will optimise our communication and minimise our +misunderstandings and our cognitive load. We will aim use the same terms in: + +- the UI of the service +- the code we write +- our sketches and mockups +- our research sessions +- our documentation and our presentations to partner organisations + +## Terms + +We are provided with daily **`forecasts`** by CERC. Each forecast consists of 6 +environmental **`predictions`**: + +- Air pollution +- UV +- Pollen +- Temperature +- Wind +- Rain + +Each **prediction** has an **`DAQI level`**. This [DAQI (Daily Air +Quality Index)][] scoring uses the range 1-10: + +- low (1-3) +- moderate (4-6) +- high (7-9) +- very high (10) + +An **`alert`** is in effect when a particular prediction's DAQI level is above a +certain threshold e.g. tomorrow the: + +- UV prediction has the **moderate** DAQI level +- pollen prediction has the **low** DAQI level +- air pollution prediction has the **high** DAQI level (aka an "**Air quality + alert**: high") + +**Air quality alerts** are air pollution predictions with DAQI leveles above +"low". + +[DAQI (Daily Air Quality Index)]: https://uk-air.defra.gov.uk/air-pollution/daqi