Document process for creating proposals and submissions in a3p-integration. #9093
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@turadg I needed to write this down again so I could refactor a proposal. Would you help me make this more correct? Or at least correct enough to check in. |
Chris-Hibbert
force-pushed
the
8740-replacePriceFeeds
branch
from
f57210e to
841c9c9
Compare
turadg
requested changes
Mar 15, 2024
a3p-integration/README.md
Outdated
|
|
||
| For an example, see `a:upgrade-next` in master. | ||
|
|
||
| ### Core-eval proposal | ||
|
|
||
| The `type` of a core-eval proposal is `"/agoric.swingset.CoreEvalProposal"`, and content is submitted from a `submission` subfolder. | ||
| The `type` of a core-eval proposal is `"/agoric.swingset.CoreEvalProposal"`, and content is submitted from a subfolder whose name defaults to `submission`. |
There was a problem hiding this comment.
Suggested change
| The `type` of a core-eval proposal is `"/agoric.swingset.CoreEvalProposal"`, and content is submitted from a subfolder whose name defaults to `submission`. | |
| The `type` of a core-eval proposal is `"/agoric.swingset.CoreEvalProposal"`. By default the submission in the subdir `submission` is evaluated. The proposal package can override this by providing an `eval.sh` that is executed instead. See [run_eval.sh](https://github.com/Agoric/agoric-3-proposals/blob/main/packages/synthetic-chain/public/upgrade-test-scripts/run_eval.sh) |
a3p-integration/README.md
Outdated
|
|
||
| If the proposal is planned to be executed after the chain software upgrade, and the source of the proposal is in `agoric-sdk`, it's recommended to not check-in the `submission` content in source control and instead generate it automatically when testing. Since proposals cannot access SDK code, a script can be used to generate the `submission` content. Until there is [native support for build scripts in the `synthetic-chain` tool](https://github.com/Agoric/agoric-3-proposals/issues/87), `a3p-integration`'s `build:submissions` step invokes `/script/generate-a3p-submission.sh` in `agoric-sdk` before starting the upgrade test. | ||
| If the proposal is planned to be executed after the chain software upgrade, and the source of the proposal is in `agoric-sdk`, it's recommended to not check-in the `submission` content in source control and instead generate it automatically when testing. Since proposals cannot access SDK code, a script can be used to generate the `submission` content. Until there is [native support for build scripts in the `synthetic-chain` tool](https://github.com/Agoric/agoric-3-proposals/issues/87), `a3p-integration`'s `build:submissions` step invokes `/script/generate-a3p-submissions.sh` in `agoric-sdk` before starting the upgrade test. |
There was a problem hiding this comment.
Suggested change
| If the proposal is planned to be executed after the chain software upgrade, and the source of the proposal is in `agoric-sdk`, it's recommended to not check-in the `submission` content in source control and instead generate it automatically when testing. Since proposals cannot access SDK code, a script can be used to generate the `submission` content. Until there is [native support for build scripts in the `synthetic-chain` tool](https://github.com/Agoric/agoric-3-proposals/issues/87), `a3p-integration`'s `build:submissions` step invokes `/script/generate-a3p-submissions.sh` in `agoric-sdk` before starting the upgrade test. | |
| If the proposal is planned to be executed after the chain software upgrade, and the source of the proposal is in `agoric-sdk`, don't commit the built proposal because CI will test that instead of the current code. | |
| Instead generate it automatically in each test run. Since proposals cannot access SDK code, a script can be used to generate the `submission` content. Until there is [native support for build scripts in the `synthetic-chain` tool](https://github.com/Agoric/agoric-3-proposals/issues/87), `a3p-integration`'s `build:submissions` step invokes `generate-a3p-submissions.sh` before starting the upgrade test. |
a3p-integration/README.md
Outdated
|
|
||
| Submissions that don't need to pass in options or generate references to source | ||
| bundles can be written directly in a `foo-submission` subdirectory of the | ||
| proposal. These would incude a .js or .tjs file, accompanied by a similarly-named |
There was a problem hiding this comment.
Suggested change
| proposal. These would incude a .js or .tjs file, accompanied by a similarly-named | |
| proposal. These would include a .js script, accompanied by a similarly-named |
a3p-integration/README.md
Outdated
| parameter. | ||
|
|
||
| If the submission does require a bundle reference, or other options to be | ||
| provided, it should be written as two parts. The proposal usually goes in |
There was a problem hiding this comment.
Suggested change
| provided, it should be written as two parts. The proposal usually goes in | |
| provided, it should be written as two parts: a core eval and a builder for it. E.g. |
a3p-integration/README.md
Outdated
| provided, it should be written as two parts. The proposal usually goes in | ||
| `.../vats/proposals`, and the script in `.../builders/scripts/vats`. | ||
|
|
||
| ### Proposal |
There was a problem hiding this comment.
From here down is not about a3p. I think it should go in deploy-script-support. cc @michaelfig @dckc for input.
There was a problem hiding this comment.
sounds about right.
I wonder about folding it into docs on Permissioned Contract Deployment too.
Meanwhile, I added it to
There was a problem hiding this comment.
Parts of the section on scripts describes how to lay out files and directories in a3p. I don't think those considerations apply to deploy-script-support. I'm trying to tease those sections apart, and understand what can be said over there.
| @@ -7,7 +7,8 @@ | |||
| "coreProposals": [] | |||
| }, | |||
| "sdk-generate": [ | |||
| "probe-zcf-bundle probe-submission" | |||
| "probe-zcf-bundle probe-submission", | |||
There was a problem hiding this comment.
please limit this PR to only Markdown and comments changes
There was a problem hiding this comment.
Oops. Wrong commit base.
Chris-Hibbert
force-pushed
the
8740-replacePriceFeeds
branch
2 times, most recently
from
c3c8034 to
8296522
Compare
Chris-Hibbert
force-pushed
the
8740-docs
branch
from
4c47805 to
d7e743d
Compare
|
apologies for rebasing, but I wanted to look at it on top of #9044. |
Chris-Hibbert
force-pushed
the
8740-docs
branch
from
d7e743d to
99968e5
Compare
|
Please take another look. It's now based directly on master, so all the extraneous stuff is gone. |
turadg
approved these changes
Apr 10, 2024
|
|
||
|
|
||
| **REVIEWERS**: _I don't know how much of this applies to building proposals for |
There was a problem hiding this comment.
a3p is running a synthetic mainnet, so it's the same either way.
remember to remove this comment before merge
Deploying agoric-sdk with
|
| Latest commit: |
0083abf
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0f302220.agoric-sdk.pages.dev |
| Branch Preview URL: | https://8740-docs.agoric-sdk.pages.dev |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
refs: #8740
Description
Improved description of creating proposals and submissions in a3p-integration
Security Considerations
None
Scaling Considerations
None
Documentation Considerations
That's it.
Testing Considerations
None
Upgrade Considerations
None