docs: a3p draft proposals

a3p-integration/README.md

@@ -60,7 +60,7 @@ For a chain software upgrade proposal, the `type` is `"Software Upgrade Proposal
 
 - `sdkImageTag` is the docker image tag to use that contains the upgraded chain software. It has a value of `unreleased`, which is the tag for the image that is built from the enclosing `agoric-sdk` repository.
 
-- `planName` is the "upgrade name" included in the proposal which must match the value in the upgraded chain software. In the `master` branch its value is `UNRELEASED_UPGRADE`. In the release branches, it's `agoric-upgrade-NN`.
+- `planName` is the "upgrade name" included in the proposal which must match the value in the upgraded chain software. In the `master` branch its value is `UNRELEASED_A3P_INTEGRATION`. In the release branches, it's `agoric-upgrade-NN`.
 
 - `upgradeInfo` contains other details passed to the governance proposal. In
    particular, it can have a `coreProposals` field which instructs the chain
@@ -115,7 +115,7 @@ The `yarn build` script automates 3 steps:
 
 ## Generate a docker image with the `agoric-sdk` chain software
 
-The chain software upgrade proposal contained in this end-to-end integration test performs an upgrade of the agoric-3 synthetic chain to an `UNRELEASED_UPGRADE` plan name (or the corresponding upgrade plan name for release branches). It loads the docker image `ghcr.io/agoric/agoric-sdk:unreleased` for the software implementing that upgrade (both in the `master` branch or in release branches).
+The chain software upgrade proposal contained in this end-to-end integration test performs an upgrade of the agoric-3 synthetic chain to an `UNRELEASED_A3P_INTEGRATION` plan name (or the corresponding upgrade plan name for release branches). It loads the docker image `ghcr.io/agoric/agoric-sdk:unreleased` for the software implementing that upgrade (both in the `master` branch or in release branches).
 
 The upgrade handler is implemented by the code in the enclosing `agoric-sdk` repository. After any change to the chain software or vat code upgraded through core proposals, the image must be regenerated. This is automatically done by the `build:sdk` script, but can also be performed manually using:
 
@@ -202,7 +202,7 @@ That's because you didn't create an image from the local `agoric-sdk`. Run `yarn
 
 If you get an error like,
 ```
-panic: UPGRADE "UNRELEASED_UPGRADE" NEEDED at height: 1101: {"coreProposals":["@agoric/builders/scripts/vats/init-network.js"]}
+panic: UPGRADE "UNRELEASED_A3P_INTEGRATION" NEEDED at height: 1101: {"coreProposals":["@agoric/builders/scripts/vats/init-network.js"]}
 ```
 
 Means your SDK image is different than the one expected by the upgrade proposal. To build the correct image, run `yarn build:sdk`.

a3p-integration/proposals/README.md

@@ -0,0 +1,96 @@
+# Draft proposals
+
+## How to publish a proposal once approved
+
+`a3p-integration` holds draft proposals to test in agoric-sdk that they perform
+as expected. Once a proposal has been approved by BLD stakers it executes on
+chain and the proposal is no longer a draft. That requires moving it to the
+agoric-3-proposals repo to become part of the `latest` image.
+
+Steps:
+1. Get the upgrade branch
+2. Build the submissions
+3. Migrate the proposal
+4. Update the `latest` iamge
+
+### Get the proposal's branch
+
+We need the actual proposal that was sent to stakers. In the case of upgrades
+(chain-halting) it will be a dedicated release branch. (E.g.
+https://github.com/Agoric/agoric-sdk/tree/dev-upgrade-16/). If you're
+publishing an "upgrade" proposal and it's called `a:upgrade-next`, keep looking;
+that is only a draft.
+
+### Build the submissions
+
+The proposals use `sdk-generate` to ensure that CI is always testing the latest
+version. But to publish we need a fixed version, to match the software upgrade
+that the BLD stakers decided on.
+
+To build that artifact,
+```
+cd a3p-integration
+scripts/build-all-submissions.sh
+```
+
+It's best practice for each output directory to end in `-submission` to make the
+migration simpler. For example,
+```
+    "sdk-generate": [
+      "vats/probe-zcf-bundle.js probe-submission",
+      "vats/test-localchain.js localchaintest-submission"
+    ],
+```
+
+### Migrate the proposal
+
+Figure out the serial number of the proposal that was voted on. Keep a link to
+it to reference. 
+
+In agoric-3-proposals, make a new `proposals/NN:PROPOSAL_NAME` directory where
+NN is the proposal's serial number. If the proposal is a chain-halting upgrade
+then it would be `NN:upgrade-KK` where KK is the agoric-sdk upgrade handler
+serial number.
+
+Copy the contents of the agoric-sdk proposal to this new directory.
+
+Verify that `planName` references the go upgrade handler.
+
+Remove `sdk-generate` from package.json (because the files are already generated
+and will be checked in with the PR).
+
+Change `releaseNotes` to reference that actual release notes. [For example](https://github.com/Agoric/agoric-3-proposals/blob/c70cf299b0efc3758991639a03b92cc33867a5bf/proposals/65%3Aupgrade-13/package.json#L3),
+```
+    "releaseNotes": "https://github.com/Agoric/agoric-sdk/releases/tag/agoric-upgrade-13",
+```
+
+Change `sdkImageTag` to the number mentioned in the release notes (search for
+`ghcr.io/agoric/agoric-sdk:`) [For example](https://github.com/Agoric/agoric-3-proposals/blob/c70cf299b0efc3758991639a03b92cc33867a5bf/proposals/65%3Aupgrade-13/package.json#L3C1-L4C1),
+```
+    "sdkImageTag": "39",
+```
+
+# Update the `latest` image
+
+Once you have the new proposal in agoric-3-propals, send a PR to merge it into
+the repo. The PR's CI will test it and once the PR is merged it will update the
+`latest` image.
+
+## How to revise this directory after 
+
+Once `latest` has changed, if it was a Software Upgrade Proposal then the
+upgrade handler in master will fail.  If that poses a problem, you can set
+a3p-integration `agoricSyntheticChain.fromTag` to a specific version instead
+of `latest`. See https://ghcr.io/agoric/agoric-3-proposals for the available
+tags.
+
+You need to revise `a:upgrade-next` to be able to apply on top of the last
+upgrade. In master it should already have these values, which should be
+maintained:
+```
+    "releaseNotes": false,
+    "sdkImageTag": "unreleased",
+    "planName": "UNRELEASED_A3P_INTEGRATION",
+```
+
+But you will have to remove from `app.go` whatever proposals were already executed.

a3p-integration/proposals/a:upgrade-next/README.md

@@ -1,6 +1,6 @@
 # Proposal to upgrade the chain software
 
-The `UNRELEASED_UPGRADE` software upgrade may include core proposals defined in
+The `UNRELEASED_A3P_INTEGRATION` software upgrade may include core proposals defined in
 its upgrade handler. See `CoreProposalSteps` in the `unreleasedUpgradeHandler`
 in [golang/cosmos/app/app.go](../../../golang/cosmos/app/app.go).