From f3060e349386e5d7af3f2a33068da5e24d886f88 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Thu, 2 Nov 2023 14:27:51 -0700
Subject: [PATCH] clean up docs

---
 CONTRIBUTING.md   |  9 +++++++++
 README.md         | 44 ++++++++++++++++++++++++++++++++++++++++----
 makeDockerfile.ts | 23 +++++++++++++++++++++--
 3 files changed, 70 insertions(+), 6 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..43e0616c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,9 @@
+# Adding a proposal
+
+Each proposal to Mainnet (agoric-3) should be contributed to this repo before being proposed to the chain.
+
+1. Prepare the proposal and verify it running locally
+2. Submit a PR to this repo in which the proposal has a _pending_ name (e.g. `a:my-contract`)
+3. Get review and merge to main
+4. When the proposal has been further qualified with higher fidelity to Mainnet, submit to Mainnet
+5. When the proposal passes, submit a PR here converting the pending proposal to a passed one (by changing the letter to the submission number)
diff --git a/README.md b/README.md
index 74092a04..fc08be67 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,9 @@ This repo serves several functions:
 - publishing an image with all passed proposals (TODO: https://github.com/Agoric/agoric-3-proposals/issues/6)
 - verify that certain tests pass after each proposal
 
-# Stages
+# Design
+
+## Stages
 
 The build is [multi-stage](https://docs.docker.com/build/building/multi-stage/) with several kinds of stages:
 
@@ -24,9 +26,15 @@ All proposals then have two additional stages:
 
 The `TEST` stage does not RUN as part of the build. It only deifnes the ENTRYPOINT and CI runs them all.
 
-# Adding a proposal
+## Proposals
+
+### Types
+
+- Software Upgrade à la https://hub.cosmos.network/main/hub-tutorials/live-upgrade-tutorial.html
+- Core Eval
+- Not yet supported: combo Upgrade/Eval
 
-## Naming
+### Naming
 
 Each proposal is defined as a subdirectory of `propoals`. E.g. `16:upgrade-8`.
 
@@ -36,14 +44,42 @@ The string after `:` is the local label for the proposal. It should be distinct,
 
 If the proposal is _pending_ and does not yet have a number, use a letter. The proposals are run in lexical order so all letters execute after all the numbers are done.
 
-## Files
+### Files
 
 - `config.json` specifies what kind of proposal it is. If it's a "Software Upgrade Proposal" it also includes additional parameters.
 - `use.sh` is the script that will be run in the USE stage of the build
 - `test.sh` is the script that will be _included_ in the TEST stage of the build, and run in CI
 
+# Usage
+
+To build the test images,
+
+```
+./buildTestImages.ts
+```
+
+To build the test images for particular proposals,
+
+```
+# build just upgrades
+./buildTestImages.ts --match upgrade
+```
+
+To run the tests for particular proposals,
+
+```
+# build just upgrades
+./runTestImages.ts --match upgrade
+```
+
+To add a proposal, see [./CONTRIBUTING.md]
+
 ## Future work
 
 - [ ] include a way to test soft patches that weren't proposals (e.g. PismoB)
 - [ ] documentation and tooling for debugging
 - [ ] separate console output for agd and the scripts (had been with tmux before but trouble, try Docker compose)
+- [ ] remove use of `agoric-sdk:dev`; that's a concern of SDK
+- [ ] separate agd and actions/test services with docker-compose (https://github.com/Agoric/agoric-sdk/discussions/8480#discussioncomment-7438329)
+- [ ] way to query capdata in one shot (not resorting to follow jsonlines hackery)
+- [ ] within each proposal, separate dirs for supporting files so images don't invalidate
diff --git a/makeDockerfile.ts b/makeDockerfile.ts
index 3e9c8848..23537cf3 100755
--- a/makeDockerfile.ts
+++ b/makeDockerfile.ts
@@ -36,7 +36,9 @@ RUN /usr/src/upgrade-test-scripts/start_ag0.sh
 `;
   },
   /**
-   * stage that only runs the upgrade handler
+   * Prepare an upgrade handler to run.
+   *
+   * - Submit the software-upgrade proposal for planName and run until upgradeHeight, leaving the state-dir ready for next agd.
    */
   PREPARE(
     { planName, proposalName }: SoftwareUpgradeProposal,
@@ -44,6 +46,7 @@ RUN /usr/src/upgrade-test-scripts/start_ag0.sh
   ) {
     return `
 # PREPARE ${proposalName}
+// 
 # upgrading to ${planName}
 FROM use-${lastProposal.proposalName} as prepare-${proposalName}
 ENV UPGRADE_TO=${planName}
@@ -56,7 +59,9 @@ RUN ./start_to_to.sh
 `;
   },
   /**
-   * Execute a prepared upgrade
+   * Execute a prepared upgrade.
+   * - Start agd with the SDK that has the upgradeHandler
+   * - Run any core-evals associated with the proposal (either the ones specified in prepare, or straight from the proposal)
    */
   EXECUTE({ proposalName, planName, sdkVersion }: SoftwareUpgradeProposal) {
     return `
@@ -76,6 +81,7 @@ RUN ./start_to_to.sh
   },
   /**
    * Run a core-eval proposal
+   * - Run the core-eval scripts from the proposal. They are only guaranteed to have started, not completed.
    */
   EVAL(
     { proposalIdentifier, proposalName }: CoreEvalProposal,
@@ -92,6 +98,11 @@ SHELL ["/bin/bash", "-c"]
 RUN ./run_eval.sh ${proposalIdentifier}:${proposalName}
 `;
   },
+  /**
+   * Use the proposal
+   *
+   * - Perform any mutations that should be part of chain history
+   */
   USE({ proposalName, proposalIdentifier, type }: ProposalInfo) {
     const previousStage =
       type === 'Software Upgrade Proposal' ? 'execute' : 'eval';
@@ -111,6 +122,14 @@ SHELL ["/bin/bash", "-c"]
 RUN ./run_use.sh ${proposalIdentifier}:${proposalName}
 `;
   },
+  /**
+   * Generate image than can test the proposal
+   *
+   * - Run with the image of the last "use"
+   * - Run tests of the proposal
+   *
+   * Needs to be an image to have access to the SwingSet db. run it with `docker run --rm` to not make the container ephemeral.
+   */
   TEST({ proposalName, proposalIdentifier }: ProposalInfo) {
     return `
 # TEST ${proposalName}