Updates to readmes.

README.md

@@ -2,13 +2,64 @@
 
 The future Daily Edition app.
 
-## setup
+## Setup
+
+The project uses [nvm](https://github.com/nvm-sh/nvm) so this will need to be installed before if it's not already. Do not install it using brew.
+
+Once nvm is installed run `nvm use`.
+
+Run `make install`, this will install the dependencies for all sub-projects.
 
-Run `make install`.
 You will need `frontend` and `cmsFronts` credentials loaded.
 
 ## App setup
 
 To run the client-side app, cd into `projects/Mallard` and check out it's [README](https://github.com/guardian/editions/tree/master/projects/Mallard).
 
-![image](https://user-images.githubusercontent.com/11539094/56376453-d2a38f80-61ff-11e9-9c78-c2875b22b551.png)
+## Subprojects
+
+The project is split into several sub projects, located in the projects directory. Each of these contains a `package.json` and `README.md` file.
+
+## Installing, building, testing and linting
+
+Make targets are used to build, lint, test and install dependencies. These can either run against one, some, or all of the subprojects.
+
+-   `make install` install node dependencies with yarn
+-   `make validate` run lint
+-   `make fix` run lint with autofix
+-   `make test` run unit tests
+-   `make build` compile
+-   `make clean` delete node modules and other build related things
+-   `make list`
+
+To run a make target against one project only, follow it with `-` and the project name:
+
+`make install-Mallard`
+
+To exclude one or more projects, set the `EXCLUDE` environment variable to the names of the project seperated by spaces. This is used on CI to produce backend only builds.
+
+### [Mallard](https://github.com/guardian/editions/tree/master/projects/Mallard)
+
+This is the mobile app for downloading and viewing Editions. It runs on Android and iOS via react-native.
+
+### [backend](https://github.com/guardian/editions/tree/master/projects/backend)
+
+This is the lambda which turns CAPI, fronts data and images into a format the app can use, it can be run as a local http service for development.
+
+### [archiver](https://github.com/guardian/editions/tree/master/projects/archiver)
+
+This is a collection of lambdas which form a step function which uses the backend to generate the contents of the S3 buckets which the app reads from.
+
+### [aws](https://github.com/guardian/editions/tree/master/projects/aws)
+
+This is the Amazon architecture for the backend and archiver, expressed as cdk.
+
+### [Apps](https://github.com/guardian/editions/tree/master/projects/Apps)
+
+This contains `common` which is the code shared between app and backends and `crosswords` which is the crossword.
+
+## Deployment
+
+### backend, archiver and aws
+
+These are deployed using [riffraff](https://riffraff.gutools.co.uk) as `editions`.

projects/Apps/package.json

@@ -4,7 +4,7 @@
     "description": "Monorepo for React Native Apps",
     "main": "index.js",
     "scripts": {
-        "test": "echo 'Apps require no tests'",
+        "test": "yarn workspace @guardian/editions-common run test",
         "build": "echo 'Apps does not need building.'"
     },
     "author": "The Guardian",

projects/Mallard/README.md

@@ -2,36 +2,12 @@
 
 ## Installing
 
-rn update: run this to clear your cache
-(https://medium.com/@abhisheknalwaya/how-to-clear-react-native-cache-c435c258834e)
-
-```bash
-watchman watch-del-all &&
-rm -rf $TMPDIR/react-native-packager-cache-* &&
-rm -rf $TMPDIR/metro-bundler-cache-* &&
-rm -rf node_modules/ &&
-yarn cache clean &&
-yarn install &&
-yarn start -- --reset-cache
-```
-
-The project uses `nvm` so this will need to be installed before if it's not already:
-
-```bash
-$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
-```
-
-Start by installing our Node.js dependencies:
-
-```bash
-$ nvm use
-$ yarn
-```
+Follow the instructions in the [main README](https://github.com/guardian/editions/blob/master/README.md).
 
 For iOS development you will need to install Xcode from the App Store and then open it once and select "Install" on the pop up asking whether to install other required Xcode dependencies - specifically the simulator. If this doesn't appear go to `Preferences > Components` and download the latest simulator iOS version. Additionally, you need have CocoaPods installed:
 
-```
-$ gem install cocoapods # this may require `sudo` if you're not using rvm or rbenv
+```sh
+gem install cocoapods # this may require `sudo` if you're not using rvm or rbenv
 ```
 
 The following guides allow you to run the app locally on device emulators, or on real devices connected to your dev machine via USB.
@@ -95,3 +71,18 @@ If you wanna add static svgs, put them in the `assets/svgs` folder and run `yarn
 ### iPad testing
 
 To test the iPad version, run `yarn run-ipad`. To test responsive layouts, you can enter multitasking inside the iPad simulator (swipe up from the bottom of the window) and drag another app from the dock to the side until it goes into split view.
+
+### Upgrading React Native
+
+rn update: run this to clear your cache
+(https://medium.com/@abhisheknalwaya/how-to-clear-react-native-cache-c435c258834e)
+
+```bash
+watchman watch-del-all &&
+rm -rf $TMPDIR/react-native-packager-cache-* &&
+rm -rf $TMPDIR/metro-bundler-cache-* &&
+rm -rf node_modules/ &&
+yarn cache clean &&
+yarn install &&
+yarn start -- --reset-cache
+```

projects/archiver/README.md

@@ -0,0 +1,14 @@
+# Archiver
+
+## Installing
+
+Follow the instructions in the [project readme](https://github.com/guardian/editions/blob/master/README.md).
+
+## Running locally
+
+```sh
+    yarn start $function $inputJson
+```
+
+Where function is one of those named in main.ts and the inputJson is
+a small correctly escaped JSON document that should be used as input for the function.

projects/aws/README.md

@@ -2,8 +2,4 @@
 
 # Useful commands
 
- * `npm run build`   compile typescript to js
- * `npm run watch`   watch for changes and compile
- * `cdk deploy`      deploy this stack to your default AWS account/region
- * `cdk diff`        compare deployed stack with current state
- * `cdk synth`       emits the synthesized CloudFormation template
+-   `yarn build` generate the cloudformation

projects/backend/README.md

@@ -1,5 +1,9 @@
 # Backend
 
+## Installling
+
+Follow the steps in the project [readme](https://github.com/guardian/editions/blob/master/README.md).
+
 ## Running locally
 
 ### Janus
@@ -8,21 +12,10 @@ Ensure you have Janus credentials for `cmsFronts`.
 
 ### Env vars
 
-Then ensure you have some environment variables set, to do it in your current shell just run:
-
-```
-export stage=prod && export psurl=${CAPI_PREVIEW_URL} && export CAPI_KEY=test;
-```
+You will need a `.env` file from another developer to run the backend.
 
 `stage` is `prod` due to the fact that you get more results that way! The CAPI key is the canonical testing key ... if this, for whatever reason, doesn't work in future you can change it to a valid one.
 
-### Install node dependencies.
-
-```bash
-nvm use
-yarn
-```
-
 ### Run
 
 ```bash