From 4a9d3dab5c6a2e2ce1c2c1bac998a6e3aea0fe0a Mon Sep 17 00:00:00 2001
From: Jonathan Bernard <jonathan@jdbernard.com>
Date: Tue, 13 Aug 2024 09:09:31 -0500
Subject: [PATCH] Create top-level README.

---
 README.md            | 79 ++++++++++++++++++++++++++++++++++++++++++++
 operations/README.md | 10 +++---
 web/README.md        | 24 --------------
 3 files changed, 85 insertions(+), 28 deletions(-)
 create mode 100644 README.md
 delete mode 100644 web/README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d4693e1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# HFF Entry Forms
+
+## Local Development
+
+### Web
+
+```sh
+cd web
+npm install
+make serve & # or run in a separate terminal/pane
+make build # as-needed to rebuild (not using hot-reload)
+```
+
+### API
+
+```sh
+cd api
+make serve
+
+make serve-docker   # alternatively
+```
+
+## Procedures
+
+### Version Bump
+
+1. Ensure you know the current deployed version and the current "marked
+   version." Check the current deployed version by hitting the live API:
+
+       curl https://forms-api.hopefamilyfellowship.com/v1/version
+
+   and by querying ECR:
+
+       aws ecr describe-images --repository-name 063932952339.dkr.ecr.us-west-2.amazonaws.com/hff_entry_forms_api
+
+   Check the current "marked version" by looking at the latest git tag:
+
+       git tag -n
+
+2. If necessary, bump the version using:
+
+       make update-version
+
+   This will invoke `operations/update-version.sh` which:
+
+   - updates `web/package.json`,
+   - updates `web/package-lock.json`,
+   - updates `api/src/hff_entry_forms_apipkg/version.nim`,
+   - updates `api/hff_entry_forms_api.nimble`,
+   - commits all of the above, and
+   - tags the commit with the new version.
+
+#### Release Candidates (`-rcX` versions)
+
+When we are preparing to release version a new version, we first create release
+candidates. So, in preparation for releasing, for example, version 1.2.4, we
+do the following:
+
+```sh
+# Development is concluded, ready to release 1.2.4
+$ make update-version
+Last Version: 1.2.3
+New Version: 1.2.4-rc1
+
+$ TARGET_ENV=dev make deploy
+# verify successful build and deployment
+# validate the release in the dev environment
+
+$ make update-version
+Last Version: 1.2.4-rc1
+New Version: 1.2.4
+
+$ TARGET_ENV=dev make deploy
+# verify successful build and deployment
+
+$ TARGET_ENV=prod make deploy
+# verify successful build and deployment
+# validate the release in the prod environment
+```
diff --git a/operations/README.md b/operations/README.md
index 699f208..24a64fc 100644
--- a/operations/README.md
+++ b/operations/README.md
@@ -2,10 +2,12 @@
 
 ## System Components
 
-* DNS - hosted on GoDaddy
-* API Server - hosted on the `ortis` ECS cluster at JDB Software
+* DNS - managed by AWS
+* API Server - hosted on `sobeck.jdb-software.com`
 * API Loadbalancer - using the main load balancer for JDB Software
 * Web App - Served by CloudFront from an S3 bucket managed by JDB Software
 * Certificates - Manually created and validated for \*.HFF.com
-* Notion Integration - defined in Notion, token provided via AWS secrets
-  manager to the API instance running on the ortis cluster.
+* Notion Integration - defined in Notion, token provided via the environment
+  specific config files at `/etc/hff_entry_forms/{dev,prod}.env` and passed
+  into the docker container at runtime ad defined in the SystemD service file
+  (see `api/hff_entry_forms_api.service`)
diff --git a/web/README.md b/web/README.md
deleted file mode 100644
index 7560de1..0000000
--- a/web/README.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# hff-entry-form-web
-
-## Project setup
-```
-npm install
-```
-
-### Compiles and hot-reloads for development
-```
-npm run serve
-```
-
-### Compiles and minifies for production
-```
-npm run build
-```
-
-### Lints and fixes files
-```
-npm run lint
-```
-
-### Customize configuration
-See [Configuration Reference](https://cli.vuejs.org/config/).