Reconstruct Getting Started around versioned packages

kriskowal commented 2 years ago

What is the Problem Being Solved?

Up to this point, Agoric development velocity has depended upon a workflow where the dapps we are developing are linked into the agoric-sdk yarn workspace. This has allowed us to rapidly evolve the API with relatively little concern for the consequent migration churn for third-party dapps (since there aren’t many and we depend on the goodwill of early adopters as we mature the API’s based on their feedback.)

As we approach a stable Agoric SDK API, we need to begin to practice the discipline of tracking and communicating breaking changes, and conscientiously paying the full price for breaking backward compatibility. This will also help us cut with the grain of the medium: tools designed around semantic versioning will generally help us navigate gradual migrations for breaking changes. The tools will help us communicate breaking changes to users, protect users from breaking changes they are not prepared to adopt, and ensure that the full dependency graph of an application is reproducible.

Description of the Design

[x] We have already begun the process of Agoric SDK to npm release management, as described in MAINTAINING.md and CONTRIBUTING.md in Endo.
[ ] We will need to remove the preinstall script from the dapp-fungible-faucet. This is the default template for new dapps when using agoric init.
[ ] Use semver ranges in dapp-fungible-faucet instead of dist tags.
[ ] Make updating dapp-fungible-faucet dependency version ranges (both Agoric SDK and Endo.js) part of the process for Agoric SDK releases. All shallow dependencies in dapp-fungible-faucet should be pinned to the just-released version from Agoric SDK and the most recent version used by any transitive dependency of Agoric SDK.
[ ] Ensure that agoric-cli can be run through npx or yarn run with a versioned copy by changing dapp-fungible-faucet "scripts" to drive agoric commands.
[ ] Revise the Getting Started Guide https://github.com/Agoric/documentation/tree/main/main/getting-started to reflect the new workflow. For example, perhaps use npx agoric init to get started instead of cloning Agoric SDK and setting up a system-level agoric version linked to it. For example, use yarn agoric ... commands like yarn agoric start --reset or yarn agoric open.
[ ] Update the agoric-sdk/packages/agoric-cli workflow integration test.
[ ] Update the Dapp CI process. We may need to use an npm proxy and automate the synchronization of dapps to the versions faux-published from agoric-sdk.
[ ] Replace the cross-repo integration test system and rewrite the instructions for them https://github.com/Agoric/agoric-sdk/wiki/Cross-repo-Integration-Tests

Security Considerations

Test Plan

[ ] Automate and test the publication process using an npm proxy (Verdaccio). This might necessarily include automation to simulate the updates on dapp-fungible-faucet.

kriskowal commented 2 years ago

cc @turadg

mhofman commented 2 years ago

I think we also need to take another look at the upgrade process for existing dapps our users may have already created, not just the template, especially in the case of breaking changes (package name or API changes) to the dapp dependencies. For example the recent case of marshal moving from @agoric to @endo. See https://github.com/Agoric/agoric-sdk/issues/4626

Agoric / agoric-sdk