From 96ed5c4c87f63219ff8cdcd694e91b10f9a346e1 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Mon, 25 Sep 2023 19:38:47 +0200 Subject: [PATCH 01/19] docs: moved notion pages and restructured them as processes --- .../04-framework-lifecycle/01-systems.md | 74 ++++++++++ .../04-framework-lifecycle/02-semver.md | 36 +++++ .../00-abstract-contracts.md | 43 ++++++ .../03-osx-components/01-factory-contract.md | 88 ++++++++++++ .../03-osx-components/02-registry-contract.md | 45 ++++++ .../03-plugin-setup-processor.md | 54 ++++++++ .../03-osx-components/04-plugin-build.md | 36 +++++ .../03-osx-components/05-plugin-setup.md | 52 +++++++ .../04-sub-processes/aragon-update.md | 3 + .../contract-initialization.md | 131 ++++++++++++++++++ .../04-sub-processes/documentation.md | 15 ++ .../non-upgradeable-contract.md | 32 +++++ .../04-sub-processes/protocol-version.md | 54 ++++++++ .../04-sub-processes/testing.md | 45 ++++++ .../04-sub-processes/upgradeable-contract.md | 74 ++++++++++ .../04-framework-lifecycle/index.md | 15 +- 16 files changed, 796 insertions(+), 1 deletion(-) create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/contract-initialization.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/testing.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md new file mode 100644 index 000000000..37a944eae --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md @@ -0,0 +1,74 @@ +# Software Systems Running the Aragon OSx + +## Smart Contracts + +Ethereum smart contracts are created at compile time + +- with bytecode constituted by + - the constructor and its arguments + - functions with + - modifiers (in place substitution) + - visibility ( public, external, internal, private) + - mutability (pure, view) + - funds access (payable) + - constants + - storage slot definitions + - struct definitions + - event definitions + - custom errors + - enums + +During run time, the successful execution of transactions + +- alters storage slots +- produces receipts containing event logs + +with construction / initialization constituting a special. + +## The Subgraph + +The subgraph is composed of + +- entities +- event handlers listening to certain contracts and populating the entities + +OSx contract changes being relevant are: + +- addition of an event +- change of an event by + - addition, + - rearrangement + - deletion of fields +- removal of an event + +Addition of an event is a compatible change, whereas all other changes are incompatible and force the subgraph to adapt. + +## SDK, 3rd-Party Projects (Contract & Subgraph Consumers) + +The SDK (as well as 3rd-party projects) queries the subgraph and interacts with the deployed contract’s ABI. + +OSx contract changes being relevant are: + +- addition of external functions +- change of function signatures + - input, output, expected usage + - visibility + - storage mutability +- change of function bodies + - storage writes + - event changes + - changes in error handling + - different error messages + +If these changes happen on plugin-related components, i.e., + +- `IPlugin`, `Plugin`, `PluginUUPSUpgradeable`, `PluginCloneable` +- `IPluginSetup`, `PluginSetup` `PluginSetupProcessor` +- `IPluginRepo`, `PluginRepo`, `PluginRepoFactory`, `PluginRepoFactory` + +this affects integrators of the protocol. + +## App + +The App queries the subgraph and uses the SDK to interact with the contracts. +In some cases, it makes direct calls to contracts provided by us or third parties. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md new file mode 100644 index 000000000..5abd4bcff --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md @@ -0,0 +1,36 @@ +# SemVer Classification of OSx Contract Changes + +## Semantic Versioning + +We use the semver notation to version the OSx Protocol smart conctract and to classify changes into MAJOR, MINOR, or PATCH. + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. MAJOR version when you make incompatible API changes +> 2. MINOR version when you add functionality in a backwards compatible manner +> 3. PATCH version when you make backwards compatible bug fixes + +## Change Classications + +We now classify [smart contract changes](systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](systems.md#app). + +| SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | +| --------------------- | ------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| major | storage change | stateful | change, removal | adaptation needed, potential exploits, unexpected behavior | reverting calls, wrong values | reverting calls, wrong values | reverting calls, wrong values | +| major | inheritance | stateful, upgradeable | addition, change, removal | adaptation needed, storage corruption | | | | +| major | event change | logging | change, removal | | adaptation needed, errors | adaptation needed, reverting calls | reverting calls | +| major | external function header change | interface reliant | change, removal | adaptation needed, reverting calls | errors | errors, reverting calls | adaptation needed, errors | +| major | external function removal | interface reliant | removal | adaptation needed, fallback triggering, reverting calls | errors | adaptation needed, errors | adaptation needed, errors | +| major | enum change | | change, removal | potential exploits, reverting calls, unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | +| minor | storage addition | stateful, upgradeable | addition | | | | | +| minor | event addition | | addition | | adaptation needed | adaptation needed | | +| minor | external function addition | | addition | feature addition | | feature addition | feature addition | +| major, minor, patch | external function body change | | change | feature addition | | | | +| minor, patch | internal function | | addition, change, removal | | | | | +| minor, patch | enum addition | | addition | | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | +| patch | custom error | | addition, change, removal | adaptation needed | | adaptation needed | | +| patch | constant/immutable | | addition, change, removal | | | | | +| UNCLEAR | compiler version | | change | adaptation needed | | | | +| | | | | | | | | +| patch | file path | all | change | adaptation needed | adaptation needed | adaptation needed | | +| | | | | | | | | diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md new file mode 100644 index 000000000..3b41d70a7 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md @@ -0,0 +1,43 @@ +# Abstract Contract Change + +Applies to: + +- `PermissionManager` +- `CallbackHandler` +- `DaoAuthorizable` and `DaoAuthorizableUpgradeable` +- `Proposal` and `ProposalUpgradeable` + +```mermaid +flowchart TD + processStart("Abstract Contract Change") + processStart ==> implementation + subgraph implementation[Implementation] + bumpProtocolVersion[["Bump protocol version"]] + isUpgradeable{"is UUPS \n upgradeable?"} + upgradeableContractImplementation[[UUPS upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + affectsInitialization{"affects \n initialization?"} + adaptInitialization[[" adapt initialization\n in inheriting contract"]] + + bumpProtocolVersion --> isUpgradeable + isUpgradeable -->|yes| upgradeableContractImplementation --> affectsInitialization + isUpgradeable -->|no| nonUpgradeableContractImplementation --> affectsInitialization + affectsInitialization --> adaptInitialization + end + + implementation ==> testing[[Testing]] + %%subgraph testing[Testing] + %%end + + + testing ==> docs[[Documentation]] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + updateDerivedContracts["redeploy / upgrade \n inheriting contracts"] + end + + deployment ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md new file mode 100644 index 000000000..39b759a6c --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -0,0 +1,88 @@ +# Factory Change + +Applies to + +- `DAOFactory` +- `PluginRepoFactory` + +For changes in the underlying implementations (i.e., `DAO` and `PluginRepo`), see the process of [replacing upgradeable contracts](../03-sub-processes/upgradeable-contract.md). + +```mermaid +flowchart TD + processStart("Factory Change") + + processStart ==> implementation + subgraph implementation[Implementation] + + %% Standard Checks + bumpProtocolVersion[["Bump protocol version"]] + isEventAddition{"event addition?"} + isBaseChange{"is base imple- \n mentation change?"} + + %% Actions + deployNewImplementation["deplot new implementation \n contract through constructor"] + reuseOldImplementation["reuse old implementation \n contract through constructor"] + adaptConstructor["adapt the constructor"] + + %% Base Change + + bumpProtocolVersion --> isBaseChange + isBaseChange -->|yes| deployNewImplementation + isBaseChange -->|no| reuseOldImplementation + deployNewImplementation-->adaptConstructor + reuseOldImplementation-->adaptConstructor + + %% Event Change + adaptConstructor --> isEventAddition + isEventAddition -->|yes| adaptSubgraph[["Subgraph change"]] + end + + implementation ==> testing[[Testing]] + %%subgraph testing[Testing] + %%end + + testing ==> docs[[Documentation]] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + deployContract["deploy contracts"] + verifyContract["verify contracts"] + + deploySubgraph["deploy Subgraph \n now indexing old \n and new factories"] + + deployContract --> verifyContract + verifyContract --> deploySubgraph + deploySubgraph --> managingDaoProposal + + subgraph managingDaoProposal["Managing DAO Proposal"] + grantNewPermissions["grant registry permission \n for the new factory"] + revokeOldPermissions["revoke registry permission \n from the old factory"] + end + end + + deployment ==> rollout + subgraph rollout[Roll-out] + + sdkUpdate["update SDK"] + affectsSDK{"affects SDK?"} + affectsSDK -->|yes| sdkUpdate --> affectsApp + affectsSDK -->|no| affectsApp + + appUpdate["update App"] + affectsApp{"affects App?"} + affectsApp -->|yes| appUpdate --> announceUpdate + affectsApp -->|no| announceUpdate + + announceUpdate[["announce Aragon update"]] + announceUpdate --> initializationChange + + initializationChange{"initializtion \n change?"} + initializationChange -->|yes| upgradeToAndCall["upgrade \n via upgradeToAndCall() \n and initializeFrom()"] + initializationChange -->|no| upgradeTo["upgrade \n via upgradeTo()"] + + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md new file mode 100644 index 000000000..c5db34326 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md @@ -0,0 +1,45 @@ +# Registry Contract Change + +Applies to + +- `DAORegistry` +- `PluginRepoRegistry` + +```mermaid +flowchart TD + processStart("Registry change") + processStart ==> implementation + subgraph implementation[Implementation] + bumpProtocolVersion[["Bump protocol version"]] + upgradeableContractImplementation[[UUPS upgradeable contract \n change]] + + bumpProtocolVersion --> upgradeableContractImplementation + end + + implementation ==> testing[[Testing]] + %%subgraph testing[Testing] + %%end + + testing ==> docs[[Documentation]] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + affectsPermissions{"affects \n permissions?"} + + subgraph managingDaoProposal["Managing DAO Proposal"] + grantNewPermissions["grant new permissions \n to registry users"] + revokeOldPermissions["revoke old permissions \n from registry users"] + end + + affectsPermissions -->|yes| managingDaoProposal + end + + deployment ==> rollout + subgraph rollout[Roll-out] + %% todo + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md new file mode 100644 index 000000000..ae8ca8ea3 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md @@ -0,0 +1,54 @@ +# `PluginSetupProcessor` + +```mermaid +flowchart TD + processStart("Process Name") + processStart ==> implementation + subgraph implementation[Implementation] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + ensureCompatibility["ensure backwards compat- \n ibilitywith active setups"] + + nonUpgradeableContractImplementation --> ensureCompatibility + end + + implementation ==> testing[Testing] + %%subgraph testing[Testing] + %%end + + testing ==> docs[Documentation] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + deployContract["deploy the contract"] + redeployDaoFactory[[redeploy DAOFactory]] + deploySubgraph["deploy Subgraph \n indexing the old and new \n PluginSetupProcessor"] + deployContract --> redeployDaoFactory --> deploySubgraph + end + + deployment ==> rollout + subgraph rollout[Roll-out] + sdkUpdate["update SDK"] + appUpdate["update App"] + + announceUpdate["Announce Update"] + revokeApplyPermissions["create proposal to grant/revoke \n APPLY...PERMISSION to/from \n new/old PluginSetupProcessor"] + + sdkUpdate -->|yes| appUpdate + appUpdate--> announceUpdate + announceUpdate --> revokeApplyPermissions + end + + rollout ==> processEnd("Done") +``` + +## Ensuring backwards compatibility + +- ensure backwards compatibility with old setups + - use the old `mapping(bytes32 => PluginState) public states;` mapping + - Update Subgraph & SDK to be able to handle both old & new `PluginSetupProcessor` + +## Roll-Out + +Inform plugin developers to use the new contract. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md new file mode 100644 index 000000000..5b1c9dbf4 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md @@ -0,0 +1,36 @@ +# Plugin Build + +```mermaid +flowchart TD + processStart("Plugin Build") + processStart ==> implementation + subgraph implementation[Implementation] + isUpgradeable{"is UUPS \n upgradeable?"} + upgradeableContractImplementation[[UUPS upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + adaptPluginSetup[[implement PluginSetup]] + isUpgradeable -->|yes| upgradeableContractImplementation --> adaptPluginSetup + isUpgradeable -->|no| nonUpgradeableContractImplementation --> adaptPluginSetup + + end + + implementation ==> testing[Testing] + %%subgraph testing[Testing] + %%end + + testing ==> docs[Documentation] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + deployViaSetup[["deploy the build \n in the associated \n PluginSetup"]] + end + + deployment ==> rollout + subgraph rollout[Roll-out] + publishPluginSetup[[publish PluginSetup]] + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md new file mode 100644 index 000000000..59d226c94 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md @@ -0,0 +1,52 @@ +# Plugin Setup + +:::todo +PAGE IS WORK IN PROGRESS +::: + +```mermaid +flowchart TD + processStart("Publish a PluginSetup") + processStart ==> implementation + subgraph implementation[Implementation] + implementPrepareInstallation[["implement \n prepareInstallation()"]] + implementPrepareUninstallation[["implement \n prepareUninstallation()"]] + isUpgradeable{"UUPS upgrade- \n able plugin?"} + implementPrepareUpdate[["implement \n prepareUpdate()"]] + updateMetadata[["update metadata"]] + + implementPrepareInstallation --> implementPrepareUninstallation + implementPrepareUninstallation --> isUpgradeable + isUpgradeable -->|yes| implementPrepareUpdate --> updateMetadata + isUpgradeable -->|no| updateMetadata + end + + implementation ==> testing[[Testing]] + %%subgraph testing[Testing] + %%end + + testing ==> docs[[Documentation]] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + + end + + deployment ==> rollout + subgraph rollout[Roll-out] + isAragonPlugin{"is Aragon \n plugin?"} + managingDaoProposal["management DAO \n proposal"] + announceUpdate[["announce Aragon update"]] + + publishToAragonPluginRepo["publish PluginSetup \n in Aragon PluginRepo"] + publishToPluginRepo["publish PluginSetup \n in 3rd-party repo"] + + isAragonPlugin -->|yes| managingDaoProposal --> publishToAragonPluginRepo --> announceUpdate + isAragonPlugin --->|no| publishToPluginRepo + + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md new file mode 100644 index 000000000..4c6eba0c8 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md @@ -0,0 +1,3 @@ +# Aragon Update + +TODO diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/contract-initialization.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/contract-initialization.md new file mode 100644 index 000000000..397d251ce --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/contract-initialization.md @@ -0,0 +1,131 @@ +# Initialization Change + +```mermaid +flowchart TD + init[["Change in initialization"]] + + %% Checks + isImmutable{"is immutable \n variable?"} + isUpgradeable{"is contract UUPS \n upgradeable?"} + isCloneable{"is contract \n cloneable?"} + isVersioned{"is contract \n versioned?"} + + %% Actions + reinitialize[["increment the reinitializer number"]] + reinitializeFrom[["increment the reinitializer number \n in the initializeFrom() function"]] + adaptConstructor[["adapt the constructor"]] + adaptInitialize[["adapt the initialize() \n function"]] + adaptInitializeFrom[["adapt the initializeFrom() \n function"]] + + %% Process + init --> isImmutable + isImmutable -->|yes| adaptConstructor + isImmutable -->|no| isUpgradeable + + isUpgradeable -->|no| isCloneable + isUpgradeable -->|yes| reinitialize --> adaptInitialize + + isCloneable -->|no| adaptConstructor + isCloneable -->|yes| adaptInitialize + + reinitialize --> isVersioned + + isVersioned -->|yes| reinitializeFrom --> adaptInitializeFrom +``` + +## UUPSUpgradeable Contracts + +### Incrementing the `reinitializer` number + +Let's imagine we released version 1.2.0 of an upgradeable contract. + +```solidity +function protocolVersion() public pure returns (uint8[3] memory) { + return [1, 2, 0]; +} +``` + +and previously the following versions were released: + +1. `1.0.0` +2. `1.0.1` +3. `1.1.0` +4. `1.1.1` + +Accordingly, `v1.2.0` is the 5th version and our `reinitializer()` number is `5` (assuming that all versions require initialization). + +### Adapting the `initialize` function + +First, change the `reinitializer(5)` and make sure that there is a test for it. + +:::todo +We must write tests for this. +::: + +Then do all the initialzation changes and write a note, in which version they have been introduced (for easier traceability) + +```solidity +function initialize(uint256 calldata _a, address calldata _c) external reinitializer(5) { + // v1.0.0 + a = _a; + + // v1.0.1 + internalCallB(); + + // v1.1.0 + c = _c; + + // v1.1.1 + emit EventD(); + + // v1.2.0 + externalCallE(); + emit EventE(); +} +``` + +### Adapting the `initializeFrom` function + +This would result in an `initializeFrom` function of the following form: + +```solidity +function initializeFrom( + uint8[3] calldata _previousProtocolVersion, + bytes calldata _initData +) external reinitializer(5) { + // Ensure that the previous and current protocol MAJOR version numbers match. If not, revert because the upgrade is incompatible since breaking changes occured. + if (_previousProtocolVersion[0] != protocolVersion()[0]) { + revert('Incompatible upgrade'); + } + + // Everybody will have at least a v1.0.0 contract initialized so we don't need to check for `_previousProtocolVersion.lte([1, 0, 0])` + + if (_previousProtocolVersion.lte([1, 0, 1])) { + internalCallB(); + } + + if (_previousProtocolVersion.lte([1, 1, 0])) { + c = _c; + } + + if (_previousProtocolVersion.lte([1, 1, 1])) { + emit EventD(); + } + + if (_previousProtocolVersion.lte([1, 2, 0])) { + externalCallE(); + emit EventE(); + } +} +``` + +If we now upgrade from the previous version `1.0.1` to `1.2.0`, we would apply the initialization steps required for + +- `1.1.0` +- `1.1.1` + +Written this way, the `initializeFrom` function ensures that all initializations that have happened in between the two versions are applied. + +:::todo +We have to implement the less than comparator `function lt(uint[3] memory lhs, uint[3] memory lhs) internal pure returns (bool)`. +::: diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md new file mode 100644 index 000000000..212caf7f8 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md @@ -0,0 +1,15 @@ +# Documentation + +```mermaid +flowchart TD + + updateSpecs[["update product specs"]] + updateDocs[["update the dev portal"]] + + updateSpecs --> updateDocs + +``` + +## Update Product Specs + +## Upgade the Developer Portal diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md new file mode 100644 index 000000000..d085bbfd4 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md @@ -0,0 +1,32 @@ +# Non-Upgradeable Contract Change + +TODO TODO + +```mermaid +flowchart TD + processStart("Non-upgradeable contract") + processStart ==> implementation + subgraph implementation[Implementation] + end + + implementation ==> testing + subgraph testing[Testing] + + end + + testing ==> docs + subgraph docs[Documentation] + end + + docs ==> deployment + subgraph deployment[Deployment] + + end + + deployment ==> rollout + subgraph rollout[Roll-out] + + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md new file mode 100644 index 000000000..b9ec27f06 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md @@ -0,0 +1,54 @@ +# Protocol Version Bump + +```mermaid +flowchart TD + + processStart("Protocol Version Change") + + bumpProtocolVersion["Bump the global \n ProtocolVersion number"] + mostDerivedCheck["Check that all most derived contracts \n inherit from the ProtocolVersion contract"] + adaptInitializeFrom[["adapt the initializeFrom() \n function of affected contracts"]] + + processStart --> bumpProtocolVersion + + bumpProtocolVersion --> mostDerivedCheck + + mostDerivedCheck --> adaptInitializeFrom + + adaptInitializeFrom --> processEnd("Done") +``` + +## Semantic Versioning + +We use the semver notation to version the OSx Protocol smart conctract and to classify changes into MAJOR, MINOR, or PATCH. + +> Given a version number MAJOR.MINOR.PATCH, increment the: +> +> 1. MAJOR version when you make incompatible API changes +> 2. MINOR version when you add functionality in a backwards compatible manner +> 3. PATCH version when you make backwards compatible bug fixes + +### Change Classications + +We now classify [smart contract changes](../01-systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](../01-systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](../01-systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](../01-systems.md#app). + +| SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | +| --------------------- | ------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| major | storage change | stateful | change, removal | adaptation needed, potential exploits, unexpected behavior | reverting calls, wrong values | reverting calls, wrong values | reverting calls, wrong values | +| major | inheritance | stateful, upgradeable | addition, change, removal | adaptation needed, storage corruption | | | | +| major | event change | logging | change, removal | | adaptation needed, errors | adaptation needed, reverting calls | reverting calls | +| major | external function header change | interface reliant | change, removal | adaptation needed, reverting calls | errors | errors, reverting calls | adaptation needed, errors | +| major | external function removal | interface reliant | removal | adaptation needed, fallback triggering, reverting calls | errors | adaptation needed, errors | adaptation needed, errors | +| major | enum change | | change, removal | potential exploits, reverting calls, unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | +| minor | storage addition | stateful, upgradeable | addition | | | | | +| minor | event addition | | addition | | adaptation needed | adaptation needed | | +| minor | external function addition | | addition | feature addition | | feature addition | feature addition | +| major, minor, patch | external function body change | | change | feature addition | | | | +| minor, patch | internal function | | addition, change, removal | | | | | +| minor, patch | enum addition | | addition | | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | +| patch | custom error | | addition, change, removal | adaptation needed | | adaptation needed | | +| patch | constant/immutable | | addition, change, removal | | | | | +| UNCLEAR | compiler version | | change | adaptation needed | | | | +| | | | | | | | | +| patch | file path | all | change | adaptation needed | adaptation needed | adaptation needed | | +| | | | | | | | | diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/testing.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/testing.md new file mode 100644 index 000000000..93e67b8fb --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/testing.md @@ -0,0 +1,45 @@ +# Testing + +Unit testing, integration testing, and regression testing are three distinct phases of software testing, each with its own scope and purpose. These testing types serve different roles in ensuring the quality and reliability of software applications. + +In summary, unit testing focuses on verifying individual code units, integration testing ensures that units work together correctly, and regression testing guards against unintended side effects when changes are made to the software. All three testing types are essential for building robust and maintainable software applications, and they are often used in combination to achieve comprehensive test coverage. + +```mermaid +flowchart TD + processStart("Testing") + unitTests[["write unit tests"]] + regressionTests[["write regression tests"]] + integrationTests[["write integration tests"]] + runTests["run tests locally and on CI \n for every PR / commit"] + processEnd("Done") + + processStart --> unitTests --> regressionTests--> integrationTests --> runTests --> processEnd +``` + +## Unit Testing + +**Scope:** Unit testing focuses on testing individual components or units of code in isolation. A unit can be a function, method, class, or a small section of code. The goal is to verify that each unit of code works correctly according to its design and specifications. +**Purpose:** Unit testing helps identify and fix bugs and issues at the smallest possible level, ensuring that individual units of code perform as expected. It also supports code maintainability and helps developers catch and address issues early in the development process. +**Testing Approach:** Typically, unit tests are written by developers and executed frequently during the development process. They are isolated from external dependencies and use mock objects or stubs to simulate interactions with other components. + +## Integration Testing + +**Scope:** Integration testing focuses on testing the interactions between different units or components of a software system. It aims to ensure that these units work together as expected when integrated. +**Purpose:** Integration testing is crucial for identifying issues that may arise when units or modules interact, such as data transfer problems, communication errors, or inconsistencies in behavior. It helps verify that the components can communicate and collaborate effectively. +**Testing Approach:** Integration tests can be written by developers or dedicated testers. They involve testing the interfaces, data flows, and interactions between various units or subsystems. Integration tests may be conducted incrementally, starting with simple interactions and gradually moving to more complex scenarios. + +## Regression Testing + +**Scope:** Regression testing is focused on ensuring that changes made to the software, such as new features, bug fixes, or enhancements, do not introduce new defects or negatively impact existing functionality. It involves retesting the entire application or a subset of it. +**Purpose:** The primary purpose of regression testing is to maintain the stability and reliability of the software over time. As the software evolves, new code changes can inadvertently break existing features. Regression tests help catch these regressions early. +**Testing Approach:** Regression tests can include both unit tests and integration tests, as well as system-level tests. Test automation is often employed for regression testing to efficiently retest the software after each code change. Test suites are run regularly, ideally as part of a continuous integration (CI) or continuous delivery (CD) pipeline. + +For our smart contracts, this kind of testing is important to make sure that that we don't accidentally break the compatibility between existing contracts and new implementations. +They fill the gap between unit tests testing isolated functionalities and integration tests testing the interplay between contracts that all belong to the same OSx version. +This might include: + +- upgradeability tests against previous contract versions + - check for storage corruption + - check reinitializer number is bumped +- fork tests against currently active contracts (to ensure that interfaces and functionalities match with each other) + - current `PluginSetupProcessor`, associated `PluginRepo` etc. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md new file mode 100644 index 000000000..2b5fa0fac --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md @@ -0,0 +1,74 @@ +# UUPS Upgradeable Contract Change + +Applies to + +- `DAO` +- `PluginRepo` + +```mermaid +flowchart TD + processStart("UUPS upgradeable contract") + processStart ==> implementation + subgraph implementation[Implementation] + affectsStorageGaps{"affects sto- \n rage layout?"} + adaptStorageGaps[["adapt storage gaps"]] + + affectsSubgraph{"affects subgraph?"} + adaptSubgraph[["adapt subgraph"]] + + affectsInitialization{"affects \n initialization?"} + adaptInitialization[[" adapt initialization"]] + + affectsStorageGaps -->|yes| adaptStorageGaps + affectsStorageGaps -->|no| affectsSubgraph + + + affectsSubgraph -->|yes| adaptSubgraph + adaptSubgraph --> affectsInitialization + + adaptStorageGaps --> affectsInitialization + affectsInitialization -->|yes| adaptInitialization + end + + implementation ==> testing[[Testing]] + %%subgraph testing[Testing] + %%end + + testing ==> docs[[Documentation]] + %%subgraph testing[Testing] + %%end + + docs ==> deployment + subgraph deployment[Deployment] + deployContracts[["deploy contracts"]] + newSubgraph{"new \n subgraph?"} + deploySubgraph[["deploy subgraph"]] + + deployContracts --> newSubgraph --> deploySubgraph + + end + + deployment ==> rollout + subgraph rollout[Roll-out] + + sdkUpdate["update SDK"] + affectsSDK{"affects SDK?"} + affectsSDK -->|yes| sdkUpdate --> affectsApp + affectsSDK -->|no| affectsApp + + appUpdate["update App"] + affectsApp{"affects App?"} + affectsApp -->|yes| appUpdate --> announceUpdate + affectsApp -->|no| announceUpdate + + announceUpdate[["announce Aragon update"]] + announceUpdate --> initializationChange + + initializationChange{"initializtion \n change?"} + initializationChange -->|yes| upgradeToAndCall["upgrade \n via upgradeToAndCall() \n and initializeFrom()"] + initializationChange -->|no| upgradeTo["upgrade \n via upgradeTo()"] + + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/index.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/index.md index 584dc0f2d..9bd2b3a0c 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/index.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/index.md @@ -4,4 +4,17 @@ title: Framework Lifecycle ## Framework Lifecycle -Placeholder file until the framework lifecycle docs are finished. +This folder contains `mermaid` flow charts and accompanying process descriptions to help with replacing existing OSx contracts and related components by newer implementations. The current iteration only takes non-breaking changes into account. + +### Legend + +The shapes used in the diagrams and their meaning are shown below: + +```mermaid +flowchart TD + predefinedProcess[["Predefined process"]] + process["Process"] + decision{"Decision"} + connector((Connector)) + terminator("terminator") +``` From 9d13b8078a307556f6793bff4da78a224ac13d97 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Tue, 26 Sep 2023 14:24:55 +0200 Subject: [PATCH 02/19] docs: fix links and improved diagrams --- ...t-contracts.md => 00-abstract-contract.md} | 14 +++--- .../03-osx-components/01-factory-contract.md | 6 +-- .../02-upgradeable-contract.md} | 20 ++------- .../03-non-upgradeable-contract.md | 43 +++++++++++++++++++ ...ry-contract.md => 04-registry-contract.md} | 8 ++-- ...cessor.md => 05-plugin-setup-processor.md} | 8 ++-- ...{04-plugin-build.md => 06-plugin-build.md} | 8 ++-- ...{05-plugin-setup.md => 07-plugin-setup.md} | 4 +- ...ocol-version.md => 01-protocol-version.md} | 2 +- ...ation.md => 02-contract-initialization.md} | 0 .../{testing.md => 03-testing.md} | 0 .../04-sub-processes/04-documentation.md | 24 +++++++++++ .../04-sub-processes/05-deployment.md | 15 +++++++ .../04-sub-processes/06-aragon-update.md | 3 ++ .../04-sub-processes/aragon-update.md | 3 -- .../04-sub-processes/documentation.md | 15 ------- .../non-upgradeable-contract.md | 32 -------------- 17 files changed, 114 insertions(+), 91 deletions(-) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/{00-abstract-contracts.md => 00-abstract-contract.md} (54%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/{04-sub-processes/upgradeable-contract.md => 03-osx-components/02-upgradeable-contract.md} (71%) create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md rename packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/{02-registry-contract.md => 04-registry-contract.md} (68%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/{03-plugin-setup-processor.md => 05-plugin-setup-processor.md} (80%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/{04-plugin-build.md => 06-plugin-build.md} (66%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/{05-plugin-setup.md => 07-plugin-setup.md} (89%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/{protocol-version.md => 01-protocol-version.md} (98%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/{contract-initialization.md => 02-contract-initialization.md} (100%) rename packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/{testing.md => 03-testing.md} (100%) create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/06-aragon-update.md delete mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md delete mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md delete mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md similarity index 54% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md index 3b41d70a7..112d6c0d7 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contracts.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md @@ -12,12 +12,12 @@ flowchart TD processStart("Abstract Contract Change") processStart ==> implementation subgraph implementation[Implementation] - bumpProtocolVersion[["Bump protocol version"]] + bumpProtocolVersion[["Bump protocol version"]] isUpgradeable{"is UUPS \n upgradeable?"} - upgradeableContractImplementation[[UUPS upgradeable \n contract change]] - nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + upgradeableContractImplementation[[UUPS upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] affectsInitialization{"affects \n initialization?"} - adaptInitialization[[" adapt initialization\n in inheriting contract"]] + adaptInitialization[[" adapt initialization\n in inheriting contract"]] bumpProtocolVersion --> isUpgradeable isUpgradeable -->|yes| upgradeableContractImplementation --> affectsInitialization @@ -25,18 +25,18 @@ flowchart TD affectsInitialization --> adaptInitialization end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end docs ==> deployment subgraph deployment[Deployment] - updateDerivedContracts["redeploy / upgrade \n inheriting contracts"] + updateDerivedContracts["upgrade / redeploy \n inheriting contracts"] end deployment ==> processEnd("Done") diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md index 39b759a6c..335c773e3 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -15,7 +15,7 @@ flowchart TD subgraph implementation[Implementation] %% Standard Checks - bumpProtocolVersion[["Bump protocol version"]] + bumpProtocolVersion[["Bump protocol version"]] isEventAddition{"event addition?"} isBaseChange{"is base imple- \n mentation change?"} @@ -37,11 +37,11 @@ flowchart TD isEventAddition -->|yes| adaptSubgraph[["Subgraph change"]] end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md similarity index 71% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md index 2b5fa0fac..a0f7dbba2 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md @@ -17,7 +17,7 @@ flowchart TD adaptSubgraph[["adapt subgraph"]] affectsInitialization{"affects \n initialization?"} - adaptInitialization[[" adapt initialization"]] + adaptInitialization[[" adapt initialization"]] affectsStorageGaps -->|yes| adaptStorageGaps affectsStorageGaps -->|no| affectsSubgraph @@ -30,23 +30,11 @@ flowchart TD affectsInitialization -->|yes| adaptInitialization end - implementation ==> testing[[Testing]] - %%subgraph testing[Testing] - %%end + implementation ==> testing[[Testing]] - testing ==> docs[[Documentation]] - %%subgraph testing[Testing] - %%end + testing ==> docs[[Documentation]] - docs ==> deployment - subgraph deployment[Deployment] - deployContracts[["deploy contracts"]] - newSubgraph{"new \n subgraph?"} - deploySubgraph[["deploy subgraph"]] - - deployContracts --> newSubgraph --> deploySubgraph - - end + docs ==> deployment[[Deployment]] deployment ==> rollout subgraph rollout[Roll-out] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md new file mode 100644 index 000000000..4940b8c8b --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md @@ -0,0 +1,43 @@ +# Non-Upgradeable Contract Change + +```mermaid +flowchart TD + processStart("Non-upgradeable contract") + processStart ==> implementation + subgraph implementation[Implementation] + + affectsSubgraph{"affects subgraph?"} + adaptSubgraph[["adapt subgraph"]] + + affectsInitialization{"affects \n initialization?"} + adaptInitialization[[" adapt initialization"]] + + affectsSubgraph -->|yes| adaptSubgraph --> affectsInitialization + affectsSubgraph -->|no| affectsInitialization + + affectsInitialization -->|yes| adaptInitialization + end + + implementation ==> testing[[Testing]] + + testing ==> docs[[Documentation]] + + docs ==> deployment[[Deployment]] + + deployment ==> rollout + subgraph rollout[Roll-out] + sdkUpdate["update SDK"] + affectsSDK{"affects SDK?"} + affectsSDK -->|yes| sdkUpdate --> affectsApp + affectsSDK -->|no| affectsApp + + appUpdate["update App"] + affectsApp{"affects App?"} + affectsApp -->|yes| appUpdate --> announceUpdate + affectsApp -->|no| announceUpdate + + announceUpdate[["announce Aragon update"]] + end + + rollout ==> processEnd("Done") +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md similarity index 68% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md index c5db34326..d81907984 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-registry-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md @@ -10,17 +10,17 @@ flowchart TD processStart("Registry change") processStart ==> implementation subgraph implementation[Implementation] - bumpProtocolVersion[["Bump protocol version"]] - upgradeableContractImplementation[[UUPS upgradeable contract \n change]] + bumpProtocolVersion[["Bump protocol version"]] + upgradeableContractImplementation[[UUPS upgradeable contract \n change]] bumpProtocolVersion --> upgradeableContractImplementation end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md similarity index 80% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md index ae8ca8ea3..da68855ab 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-plugin-setup-processor.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md @@ -5,17 +5,17 @@ flowchart TD processStart("Process Name") processStart ==> implementation subgraph implementation[Implementation] - nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] ensureCompatibility["ensure backwards compat- \n ibilitywith active setups"] nonUpgradeableContractImplementation --> ensureCompatibility end - implementation ==> testing[Testing] + implementation ==> testing[Testing] %%subgraph testing[Testing] %%end - testing ==> docs[Documentation] + testing ==> docs[Documentation] %%subgraph testing[Testing] %%end @@ -51,4 +51,4 @@ flowchart TD ## Roll-Out -Inform plugin developers to use the new contract. +Use the new contract in the Aragon CLI. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md similarity index 66% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md index 5b1c9dbf4..c65fd4250 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-plugin-build.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md @@ -6,19 +6,19 @@ flowchart TD processStart ==> implementation subgraph implementation[Implementation] isUpgradeable{"is UUPS \n upgradeable?"} - upgradeableContractImplementation[[UUPS upgradeable \n contract change]] - nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + upgradeableContractImplementation[[UUPS upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] adaptPluginSetup[[implement PluginSetup]] isUpgradeable -->|yes| upgradeableContractImplementation --> adaptPluginSetup isUpgradeable -->|no| nonUpgradeableContractImplementation --> adaptPluginSetup end - implementation ==> testing[Testing] + implementation ==> testing[Testing] %%subgraph testing[Testing] %%end - testing ==> docs[Documentation] + testing ==> docs[Documentation] %%subgraph testing[Testing] %%end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md similarity index 89% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md index 59d226c94..13220cb59 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md @@ -21,11 +21,11 @@ flowchart TD isUpgradeable -->|no| updateMetadata end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md similarity index 98% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md index b9ec27f06..2bd3f4624 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/protocol-version.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md @@ -7,7 +7,7 @@ flowchart TD bumpProtocolVersion["Bump the global \n ProtocolVersion number"] mostDerivedCheck["Check that all most derived contracts \n inherit from the ProtocolVersion contract"] - adaptInitializeFrom[["adapt the initializeFrom() \n function of affected contracts"]] + adaptInitializeFrom[["adapt the initializeFrom() \n function of affected contracts"]] processStart --> bumpProtocolVersion diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/contract-initialization.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md similarity index 100% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/contract-initialization.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/testing.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md similarity index 100% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/testing.md rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md new file mode 100644 index 000000000..a21646e36 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md @@ -0,0 +1,24 @@ +# Documentation + +```mermaid +flowchart TD + + updateSpecs[["update product specs"]] + updateDocs[["update the dev portal \n and other docs"]] + updateReadmet["update "] + updateSpecs --> updateDocs + +``` + +## Update the Product Specs + +TODO ask Sarkawt on the process of updating the specs. + +## Update the Developer Portal and other Documentation + +Alter/improve/remove all relevant pages inside + +- `packages/contracts/docs/developer-portal/01-how-it-works` +- `packages/contracts/docs/developer-portal/02-how-to-guides` + +as well as affected `README.md` files and checklists (such as the `DEPLOYMENT_CHECKLIST.md` and `UPDATE_CHECKLIST.md`). diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md new file mode 100644 index 000000000..c1b8b8372 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md @@ -0,0 +1,15 @@ +# Deployment + +```mermaid +flowchart TD + + deployContracts["deploy contracts"] + verifyContract["verify contracts"] + + newSubgraph{"new \n subgraph?"} + deploySubgraph[["deploy subgraph"]] + + deployContracts --> verifyContract --> newSubgraph --> deploySubgraph + + +``` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/06-aragon-update.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/06-aragon-update.md new file mode 100644 index 000000000..ffc587def --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/06-aragon-update.md @@ -0,0 +1,3 @@ +# Aragon Update + +This file is a placeholder. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md deleted file mode 100644 index 4c6eba0c8..000000000 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/aragon-update.md +++ /dev/null @@ -1,3 +0,0 @@ -# Aragon Update - -TODO diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md deleted file mode 100644 index 212caf7f8..000000000 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/documentation.md +++ /dev/null @@ -1,15 +0,0 @@ -# Documentation - -```mermaid -flowchart TD - - updateSpecs[["update product specs"]] - updateDocs[["update the dev portal"]] - - updateSpecs --> updateDocs - -``` - -## Update Product Specs - -## Upgade the Developer Portal diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md deleted file mode 100644 index d085bbfd4..000000000 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/non-upgradeable-contract.md +++ /dev/null @@ -1,32 +0,0 @@ -# Non-Upgradeable Contract Change - -TODO TODO - -```mermaid -flowchart TD - processStart("Non-upgradeable contract") - processStart ==> implementation - subgraph implementation[Implementation] - end - - implementation ==> testing - subgraph testing[Testing] - - end - - testing ==> docs - subgraph docs[Documentation] - end - - docs ==> deployment - subgraph deployment[Deployment] - - end - - deployment ==> rollout - subgraph rollout[Roll-out] - - end - - rollout ==> processEnd("Done") -``` From f53fa0798bc5945e525ad37ca1063fbfff148625 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Tue, 26 Sep 2023 16:11:29 +0200 Subject: [PATCH 03/19] docs: improve process descriptions --- .../03-osx-components/01-factory-contract.md | 2 +- .../02-upgradeable-contract.md | 2 +- .../03-non-upgradeable-contract.md | 4 +- .../05-plugin-setup-processor.md | 10 +---- .../03-osx-components/06-plugin-build.md | 4 +- .../03-osx-components/07-plugin-setup.md | 37 ++++++++++++++++++- .../04-sub-processes/01-protocol-version.md | 6 ++- .../02-contract-initialization.md | 8 +--- .../04-sub-processes/04-documentation.md | 9 ++--- .../04-sub-processes/05-deployment.md | 2 +- 10 files changed, 56 insertions(+), 28 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md index 335c773e3..55d2a5957 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -75,7 +75,7 @@ flowchart TD affectsApp -->|yes| appUpdate --> announceUpdate affectsApp -->|no| announceUpdate - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] announceUpdate --> initializationChange initializationChange{"initializtion \n change?"} diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md index a0f7dbba2..39d72acad 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md @@ -49,7 +49,7 @@ flowchart TD affectsApp -->|yes| appUpdate --> announceUpdate affectsApp -->|no| announceUpdate - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] announceUpdate --> initializationChange initializationChange{"initializtion \n change?"} diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md index 4940b8c8b..469d50fcc 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md @@ -33,10 +33,10 @@ flowchart TD appUpdate["update App"] affectsApp{"affects App?"} + + announceUpdate[["announce Aragon update"]] affectsApp -->|yes| appUpdate --> announceUpdate affectsApp -->|no| announceUpdate - - announceUpdate[["announce Aragon update"]] end rollout ==> processEnd("Done") diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md index da68855ab..eaab57240 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md @@ -12,12 +12,8 @@ flowchart TD end implementation ==> testing[Testing] - %%subgraph testing[Testing] - %%end testing ==> docs[Documentation] - %%subgraph testing[Testing] - %%end docs ==> deployment subgraph deployment[Deployment] @@ -32,12 +28,10 @@ flowchart TD sdkUpdate["update SDK"] appUpdate["update App"] - announceUpdate["Announce Update"] revokeApplyPermissions["create proposal to grant/revoke \n APPLY...PERMISSION to/from \n new/old PluginSetupProcessor"] sdkUpdate -->|yes| appUpdate - appUpdate--> announceUpdate - announceUpdate --> revokeApplyPermissions + appUpdate --> revokeApplyPermissions end rollout ==> processEnd("Done") @@ -51,4 +45,4 @@ flowchart TD ## Roll-Out -Use the new contract in the Aragon CLI. +Use the new `PluginSetupProcessor` in the Aragon CLI. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md index c65fd4250..85ffd2ed9 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md @@ -8,7 +8,7 @@ flowchart TD isUpgradeable{"is UUPS \n upgradeable?"} upgradeableContractImplementation[[UUPS upgradeable \n contract change]] nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] - adaptPluginSetup[[implement PluginSetup]] + adaptPluginSetup[[implement PluginSetup]] isUpgradeable -->|yes| upgradeableContractImplementation --> adaptPluginSetup isUpgradeable -->|no| nonUpgradeableContractImplementation --> adaptPluginSetup @@ -29,7 +29,7 @@ flowchart TD deployment ==> rollout subgraph rollout[Roll-out] - publishPluginSetup[[publish PluginSetup]] + publishPluginSetup[[publish PluginSetup]] end rollout ==> processEnd("Done") diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md index 13220cb59..fbb15c914 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md @@ -38,7 +38,7 @@ flowchart TD subgraph rollout[Roll-out] isAragonPlugin{"is Aragon \n plugin?"} managingDaoProposal["management DAO \n proposal"] - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] publishToAragonPluginRepo["publish PluginSetup \n in Aragon PluginRepo"] publishToPluginRepo["publish PluginSetup \n in 3rd-party repo"] @@ -50,3 +50,38 @@ flowchart TD rollout ==> processEnd("Done") ``` + +## Implement `prepareInstallation` + +Conduct all necessary actions to prepare the installation of a plugin. + +- decode `_data` if required +- deploy the plugin (proxy) contract and return its address +- deploy helpers and return their addresses via the `preparedSetupData.helpers` array of addresses. +- request new permissions to be granted and return them via the `preparedSetupData.permissions` array of permission structs. + +## Implement `prepareUninstallation` + +Conduct all necessary actions to prepare the uninstallation of a plugin and to decomission it. + +- decode `_payload._data` if required + +- request existing permissions to be revoked and return them via the `preparedSetupData.permissions` array of permission structs. + +## Implement `prepareUpdate` + +- decode `_payload._data` if required +- return initialization data to be used with `upgradeToAndCall` +- transition + - the `SetupPayload.plugin` contract + - `SetupPayload.currentHelpers` contracts + - and existing permission + +over from the `_currentBuild` to the new build by + +- deploying / decomissioning helpers return the addresses of the prevailing ones via the `preparedSetupData.helpers` array of addresses. +- requesting to grant new / revoke existing permissions and returning them via the `preparedSetupData.permissions` array of permission structs. + +## Update Metadata + +- specify the encoding of `_data` / `_payload._data` for `prepareInstallation` / `prepareUninstallation` / `prepareUpdate` in the `build-metadata.json` file accompanying the setup according to the [metadata specs](../../02-how-to-guides/02-plugin-development/07-publication/02-metadata.md). diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md index 2bd3f4624..5e0f98503 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md @@ -30,7 +30,11 @@ We use the semver notation to version the OSx Protocol smart conctract and to cl ### Change Classications -We now classify [smart contract changes](../01-systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](../01-systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](../01-systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](../01-systems.md#app). +We now classify [smart contract changes](../01-systems.md#smart-contracts) according to SemVer and how they affect + +- [The subgraph](../01-systems.md#the-subgraph) +- [the SDK or 3rd party projects](../01-systems.md#sdk-3rd-party-projects-contract--subgraph-consumers) consuming the contracts and the subgraph +- [the App](../01-systems.md#app) | SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | | --------------------- | ------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md index 397d251ce..62c4e4c09 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md @@ -58,11 +58,7 @@ Accordingly, `v1.2.0` is the 5th version and our `reinitializer()` number is `5` First, change the `reinitializer(5)` and make sure that there is a test for it. -:::todo -We must write tests for this. -::: - -Then do all the initialzation changes and write a note, in which version they have been introduced (for easier traceability) +Then do all the initialzation changes and write a note, in which version they have been introduced (for easier traceability). ```solidity function initialize(uint256 calldata _a, address calldata _c) external reinitializer(5) { @@ -127,5 +123,5 @@ If we now upgrade from the previous version `1.0.1` to `1.2.0`, we would apply t Written this way, the `initializeFrom` function ensures that all initializations that have happened in between the two versions are applied. :::todo -We have to implement the less than comparator `function lt(uint[3] memory lhs, uint[3] memory lhs) internal pure returns (bool)`. +We have to implement the less than comparator `function lte(uint[3] memory lhs, uint[3] memory lhs) internal pure returns (bool)`. ::: diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md index a21646e36..6e8fdfc87 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/04-documentation.md @@ -4,8 +4,7 @@ flowchart TD updateSpecs[["update product specs"]] - updateDocs[["update the dev portal \n and other docs"]] - updateReadmet["update "] + updateDocs[["update docs"]] updateSpecs --> updateDocs ``` @@ -14,11 +13,11 @@ flowchart TD TODO ask Sarkawt on the process of updating the specs. -## Update the Developer Portal and other Documentation +## Update the Documentation -Alter/improve/remove all relevant pages inside +Alter/improve/remove all relevant developer portal pages inside - `packages/contracts/docs/developer-portal/01-how-it-works` - `packages/contracts/docs/developer-portal/02-how-to-guides` -as well as affected `README.md` files and checklists (such as the `DEPLOYMENT_CHECKLIST.md` and `UPDATE_CHECKLIST.md`). +as well as relevant `README.md` files and checklists (i.e., `DEPLOYMENT_CHECKLIST.md` and `UPDATE_CHECKLIST.md`). diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md index c1b8b8372..db01daa91 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md @@ -7,7 +7,7 @@ flowchart TD verifyContract["verify contracts"] newSubgraph{"new \n subgraph?"} - deploySubgraph[["deploy subgraph"]] + deploySubgraph["deploy subgraph"] deployContracts --> verifyContract --> newSubgraph --> deploySubgraph From a78390cf2dd1f0174ac156ee65ba5290396e6409 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 28 Sep 2023 10:10:12 +0200 Subject: [PATCH 04/19] docs: improvements --- .../03-osx-components/01-factory-contract.md | 25 +++---------------- .../04-sub-processes/01-protocol-version.md | 4 +-- .../04-sub-processes/03-testing.md | 18 +++++++------ .../04-sub-processes/05-deployment.md | 2 +- 4 files changed, 15 insertions(+), 34 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md index 55d2a5957..3a9917cbc 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -16,7 +16,6 @@ flowchart TD %% Standard Checks bumpProtocolVersion[["Bump protocol version"]] - isEventAddition{"event addition?"} isBaseChange{"is base imple- \n mentation change?"} %% Actions @@ -25,36 +24,22 @@ flowchart TD adaptConstructor["adapt the constructor"] %% Base Change - bumpProtocolVersion --> isBaseChange isBaseChange -->|yes| deployNewImplementation isBaseChange -->|no| reuseOldImplementation deployNewImplementation-->adaptConstructor reuseOldImplementation-->adaptConstructor - %% Event Change - adaptConstructor --> isEventAddition - isEventAddition -->|yes| adaptSubgraph[["Subgraph change"]] end implementation ==> testing[[Testing]] - %%subgraph testing[Testing] - %%end testing ==> docs[[Documentation]] - %%subgraph testing[Testing] - %%end docs ==> deployment subgraph deployment[Deployment] - deployContract["deploy contracts"] - verifyContract["verify contracts"] - - deploySubgraph["deploy Subgraph \n now indexing old \n and new factories"] - - deployContract --> verifyContract - verifyContract --> deploySubgraph - deploySubgraph --> managingDaoProposal + deployContract[[standard deployment process]] + deployContract --> managingDaoProposal subgraph managingDaoProposal["Managing DAO Proposal"] grantNewPermissions["grant registry permission \n for the new factory"] @@ -76,11 +61,7 @@ flowchart TD affectsApp -->|no| announceUpdate announceUpdate[["announce Aragon update"]] - announceUpdate --> initializationChange - - initializationChange{"initializtion \n change?"} - initializationChange -->|yes| upgradeToAndCall["upgrade \n via upgradeToAndCall() \n and initializeFrom()"] - initializationChange -->|no| upgradeTo["upgrade \n via upgradeTo()"] + announceUpdate end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md index 5e0f98503..025860ed9 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md @@ -52,7 +52,5 @@ We now classify [smart contract changes](../01-systems.md#smart-contracts) accor | minor, patch | enum addition | | addition | | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | | patch | custom error | | addition, change, removal | adaptation needed | | adaptation needed | | | patch | constant/immutable | | addition, change, removal | | | | | -| UNCLEAR | compiler version | | change | adaptation needed | | | | -| | | | | | | | | +| patch | compiler version | | change | adaptation needed | | | | | patch | file path | all | change | adaptation needed | adaptation needed | adaptation needed | | -| | | | | | | | | diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md index 93e67b8fb..0e3e9f6dd 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md @@ -20,26 +20,28 @@ flowchart TD **Scope:** Unit testing focuses on testing individual components or units of code in isolation. A unit can be a function, method, class, or a small section of code. The goal is to verify that each unit of code works correctly according to its design and specifications. **Purpose:** Unit testing helps identify and fix bugs and issues at the smallest possible level, ensuring that individual units of code perform as expected. It also supports code maintainability and helps developers catch and address issues early in the development process. -**Testing Approach:** Typically, unit tests are written by developers and executed frequently during the development process. They are isolated from external dependencies and use mock objects or stubs to simulate interactions with other components. +**Testing Approach:** Typically, unit tests are isolated from external dependencies and use mock objects or stubs to simulate interactions with other components. ## Integration Testing **Scope:** Integration testing focuses on testing the interactions between different units or components of a software system. It aims to ensure that these units work together as expected when integrated. **Purpose:** Integration testing is crucial for identifying issues that may arise when units or modules interact, such as data transfer problems, communication errors, or inconsistencies in behavior. It helps verify that the components can communicate and collaborate effectively. -**Testing Approach:** Integration tests can be written by developers or dedicated testers. They involve testing the interfaces, data flows, and interactions between various units or subsystems. Integration tests may be conducted incrementally, starting with simple interactions and gradually moving to more complex scenarios. +**Testing Approach:** Integration tests involve testing the interfaces, data flows, and interactions between various units or subsystems. Integration tests may be conducted incrementally, starting with simple interactions and gradually moving to more complex scenarios. ## Regression Testing **Scope:** Regression testing is focused on ensuring that changes made to the software, such as new features, bug fixes, or enhancements, do not introduce new defects or negatively impact existing functionality. It involves retesting the entire application or a subset of it. **Purpose:** The primary purpose of regression testing is to maintain the stability and reliability of the software over time. As the software evolves, new code changes can inadvertently break existing features. Regression tests help catch these regressions early. -**Testing Approach:** Regression tests can include both unit tests and integration tests, as well as system-level tests. Test automation is often employed for regression testing to efficiently retest the software after each code change. Test suites are run regularly, ideally as part of a continuous integration (CI) or continuous delivery (CD) pipeline. +**Testing Approach:** Regression tests can include both unit tests and integration tests, as well as system-level tests. For our smart contracts, this kind of testing is important to make sure that that we don't accidentally break the compatibility between existing contracts and new implementations. They fill the gap between unit tests testing isolated functionalities and integration tests testing the interplay between contracts that all belong to the same OSx version. This might include: -- upgradeability tests against previous contract versions - - check for storage corruption - - check reinitializer number is bumped -- fork tests against currently active contracts (to ensure that interfaces and functionalities match with each other) - - current `PluginSetupProcessor`, associated `PluginRepo` etc. +- upgradeability tests against previous contract versions including + - checks for storage corruption + - checks for reinitializer number bumps +- fork tests against currently active contracts (to ensure that interfaces and functionalities match with each other) such as + - the`PluginSetupProcessor` + - `PluginRepo`s + - .... diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md index db01daa91..534f6f1d7 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md @@ -6,7 +6,7 @@ flowchart TD deployContracts["deploy contracts"] verifyContract["verify contracts"] - newSubgraph{"new \n subgraph?"} + newSubgraph{"subgraph \n change?"} deploySubgraph["deploy subgraph"] deployContracts --> verifyContract --> newSubgraph --> deploySubgraph From df400bdfbdfe78981304ab4b0b942d6dfe9a77da Mon Sep 17 00:00:00 2001 From: Michael Heuer <20623991+Michael-A-Heuer@users.noreply.github.com> Date: Fri, 6 Oct 2023 09:55:20 +0200 Subject: [PATCH 05/19] docs: apply suggestions from code review Co-authored-by: Rekard0 <5880388+Rekard0@users.noreply.github.com> --- .../03-osx-components/00-abstract-contract.md | 2 +- .../04-framework-lifecycle/04-sub-processes/05-deployment.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md index 112d6c0d7..ab5b38119 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md @@ -22,7 +22,7 @@ flowchart TD bumpProtocolVersion --> isUpgradeable isUpgradeable -->|yes| upgradeableContractImplementation --> affectsInitialization isUpgradeable -->|no| nonUpgradeableContractImplementation --> affectsInitialization - affectsInitialization --> adaptInitialization + affectsInitialization -->|yes| adaptInitialization end implementation ==> testing[[Testing]] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md index 534f6f1d7..41545f600 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/05-deployment.md @@ -9,7 +9,7 @@ flowchart TD newSubgraph{"subgraph \n change?"} deploySubgraph["deploy subgraph"] - deployContracts --> verifyContract --> newSubgraph --> deploySubgraph + deployContracts --> verifyContract --> newSubgraph -->|yes| deploySubgraph ``` From f6d6df9f713a0025dad55fe9ed09d5470fbe404a Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Fri, 6 Oct 2023 10:26:01 +0200 Subject: [PATCH 06/19] docs: corrected diagrams --- .../03-osx-components/02-upgradeable-contract.md | 7 ++++--- .../03-osx-components/03-non-upgradeable-contract.md | 9 ++++++++- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md index 39d72acad..a9f5ee54e 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md @@ -19,14 +19,15 @@ flowchart TD affectsInitialization{"affects \n initialization?"} adaptInitialization[[" adapt initialization"]] - affectsStorageGaps -->|yes| adaptStorageGaps affectsStorageGaps -->|no| affectsSubgraph + affectsStorageGaps -->|yes| adaptStorageGaps + adaptStorageGaps --> affectsSubgraph - + affectsSubgraph -->|no| affectsInitialization affectsSubgraph -->|yes| adaptSubgraph adaptSubgraph --> affectsInitialization - adaptStorageGaps --> affectsInitialization + affectsInitialization -->|yes| adaptInitialization end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md index 469d50fcc..c0cf0b687 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md @@ -12,8 +12,9 @@ flowchart TD affectsInitialization{"affects \n initialization?"} adaptInitialization[[" adapt initialization"]] - affectsSubgraph -->|yes| adaptSubgraph --> affectsInitialization affectsSubgraph -->|no| affectsInitialization + affectsSubgraph -->|yes| adaptSubgraph + adaptSubgraph --> affectsInitialization affectsInitialization -->|yes| adaptInitialization end @@ -41,3 +42,9 @@ flowchart TD rollout ==> processEnd("Done") ``` + +Hey Jessica, no worries. Generally, I would am up for this. It's just that I wasn't able to keep up with learning about the recent crosschain / L2/L3-voting development in the ecosystem. +The bigger problem I see (besides me not being on top of the recent development) is the following. +For both topics, account abstraction and crosschain Voting, we don't have a clear path or even opinion internally if and how we want to approach this subject on a technical level (i.e., do we want to implement this in OSx and if yes, how). Both topics are very challenging and as we are heavily understaffed atm. + +Because we don't have a clear idea how to approach both topics, I would personally wait with this episode until this is the case. However, I personally feel very comfortable talking about the architecture and modularity roadmap of Aragon OSx (what we have build and what others can build on top) and future ideas we have. This would require little preparation from my side. From 24580f7cd06a811aaafb3c8f7150ea666a6be07a Mon Sep 17 00:00:00 2001 From: Michael Heuer <20623991+Michael-A-Heuer@users.noreply.github.com> Date: Thu, 12 Oct 2023 09:51:54 +0200 Subject: [PATCH 07/19] docs: apply suggestions from code review Co-authored-by: Aaron Abu Usama <50079365+pythonpete32@users.noreply.github.com> --- .../developer-portal/04-framework-lifecycle/02-semver.md | 4 ++-- .../03-osx-components/00-abstract-contract.md | 6 +++--- .../03-osx-components/01-factory-contract.md | 2 +- .../03-osx-components/02-upgradeable-contract.md | 2 +- .../03-osx-components/03-non-upgradeable-contract.md | 5 ----- .../04-sub-processes/01-protocol-version.md | 4 ++-- .../04-sub-processes/02-contract-initialization.md | 2 +- .../04-framework-lifecycle/04-sub-processes/03-testing.md | 2 +- 8 files changed, 11 insertions(+), 16 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md index 5abd4bcff..79729bff3 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md @@ -2,7 +2,7 @@ ## Semantic Versioning -We use the semver notation to version the OSx Protocol smart conctract and to classify changes into MAJOR, MINOR, or PATCH. +We use the semver notation to version the OSx Protocol smart contract and to classify changes into MAJOR, MINOR, or PATCH. > Given a version number MAJOR.MINOR.PATCH, increment the: > @@ -10,7 +10,7 @@ We use the semver notation to version the OSx Protocol smart conctract and to cl > 2. MINOR version when you add functionality in a backwards compatible manner > 3. PATCH version when you make backwards compatible bug fixes -## Change Classications +## Change Classifications We now classify [smart contract changes](systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](systems.md#app). diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md index ab5b38119..98815546b 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md @@ -12,10 +12,10 @@ flowchart TD processStart("Abstract Contract Change") processStart ==> implementation subgraph implementation[Implementation] - bumpProtocolVersion[["Bump protocol version"]] + bumpProtocolVersion[["Bump protocol version"]] isUpgradeable{"is UUPS \n upgradeable?"} - upgradeableContractImplementation[[UUPS upgradeable \n contract change]] - nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + upgradeableContractImplementation[[UUPS upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] affectsInitialization{"affects \n initialization?"} adaptInitialization[[" adapt initialization\n in inheriting contract"]] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md index 3a9917cbc..bd983d602 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -19,7 +19,7 @@ flowchart TD isBaseChange{"is base imple- \n mentation change?"} %% Actions - deployNewImplementation["deplot new implementation \n contract through constructor"] + deployNewImplementation["deploy new implementation \n contract through constructor"] reuseOldImplementation["reuse old implementation \n contract through constructor"] adaptConstructor["adapt the constructor"] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md index a9f5ee54e..98f393f3b 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md @@ -53,7 +53,7 @@ flowchart TD announceUpdate[["announce Aragon update"]] announceUpdate --> initializationChange - initializationChange{"initializtion \n change?"} + initializationChange{"initialization \n change?"} initializationChange -->|yes| upgradeToAndCall["upgrade \n via upgradeToAndCall() \n and initializeFrom()"] initializationChange -->|no| upgradeTo["upgrade \n via upgradeTo()"] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md index c0cf0b687..b66d57a67 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md @@ -43,8 +43,3 @@ flowchart TD rollout ==> processEnd("Done") ``` -Hey Jessica, no worries. Generally, I would am up for this. It's just that I wasn't able to keep up with learning about the recent crosschain / L2/L3-voting development in the ecosystem. -The bigger problem I see (besides me not being on top of the recent development) is the following. -For both topics, account abstraction and crosschain Voting, we don't have a clear path or even opinion internally if and how we want to approach this subject on a technical level (i.e., do we want to implement this in OSx and if yes, how). Both topics are very challenging and as we are heavily understaffed atm. - -Because we don't have a clear idea how to approach both topics, I would personally wait with this episode until this is the case. However, I personally feel very comfortable talking about the architecture and modularity roadmap of Aragon OSx (what we have build and what others can build on top) and future ideas we have. This would require little preparation from my side. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md index 025860ed9..f9b55a769 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md @@ -20,7 +20,7 @@ flowchart TD ## Semantic Versioning -We use the semver notation to version the OSx Protocol smart conctract and to classify changes into MAJOR, MINOR, or PATCH. +We use the semver notation to version the OSx Protocol smart contract and to classify changes into MAJOR, MINOR, or PATCH. > Given a version number MAJOR.MINOR.PATCH, increment the: > @@ -28,7 +28,7 @@ We use the semver notation to version the OSx Protocol smart conctract and to cl > 2. MINOR version when you add functionality in a backwards compatible manner > 3. PATCH version when you make backwards compatible bug fixes -### Change Classications +### Change Classifications We now classify [smart contract changes](../01-systems.md#smart-contracts) according to SemVer and how they affect diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md index 62c4e4c09..91e54e867 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md @@ -123,5 +123,5 @@ If we now upgrade from the previous version `1.0.1` to `1.2.0`, we would apply t Written this way, the `initializeFrom` function ensures that all initializations that have happened in between the two versions are applied. :::todo -We have to implement the less than comparator `function lte(uint[3] memory lhs, uint[3] memory lhs) internal pure returns (bool)`. +We have to implement the less than comparator `function lte(uint[3] memory lhs, uint[3] memory rhs) internal pure returns (bool)`. ::: diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md index 0e3e9f6dd..a97445f8c 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md @@ -34,7 +34,7 @@ flowchart TD **Purpose:** The primary purpose of regression testing is to maintain the stability and reliability of the software over time. As the software evolves, new code changes can inadvertently break existing features. Regression tests help catch these regressions early. **Testing Approach:** Regression tests can include both unit tests and integration tests, as well as system-level tests. -For our smart contracts, this kind of testing is important to make sure that that we don't accidentally break the compatibility between existing contracts and new implementations. +For our smart contracts, this kind of testing is important to make sure that we don't accidentally break the compatibility between existing contracts and new implementations. They fill the gap between unit tests testing isolated functionalities and integration tests testing the interplay between contracts that all belong to the same OSx version. This might include: From dba7f1dd4b048cddc134d8e64ddb7f801ad48a32 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 10:14:46 +0200 Subject: [PATCH 08/19] docs: improved process descriptions --- .../04-framework-lifecycle/02-semver.md | 2 +- .../03-osx-components/03-non-upgradeable-contract.md | 1 - .../03-osx-components/05-plugin-setup-processor.md | 11 ++++++----- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md index 79729bff3..602583a61 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md @@ -12,7 +12,7 @@ We use the semver notation to version the OSx Protocol smart contract and to cla ## Change Classifications -We now classify [smart contract changes](systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](systems.md#app). +We now classify [smart contract changes](systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](01-systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](01-systems.md#app). | SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | | --------------------- | ------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md index b66d57a67..aeda20502 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md @@ -42,4 +42,3 @@ flowchart TD rollout ==> processEnd("Done") ``` - diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md index eaab57240..e36c32620 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md @@ -2,11 +2,11 @@ ```mermaid flowchart TD - processStart("Process Name") + processStart("PluginSetupProcessor change") processStart ==> implementation subgraph implementation[Implementation] nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] - ensureCompatibility["ensure backwards compat- \n ibilitywith active setups"] + ensureCompatibility["ensure backwards compat- \n ibility with active setups"] nonUpgradeableContractImplementation --> ensureCompatibility end @@ -39,9 +39,10 @@ flowchart TD ## Ensuring backwards compatibility -- ensure backwards compatibility with old setups - - use the old `mapping(bytes32 => PluginState) public states;` mapping - - Update Subgraph & SDK to be able to handle both old & new `PluginSetupProcessor` +Active setups are maintained in the [`mapping(bytes32 pluginInstallationId => PluginState data) public states;` mapping](../../03-reference-guide/framework/plugin/setup/PluginSetupProcessor.md#public-variable-states). +The old public mapping in the outdated `PluginSetupProcessor` can be read and accessed in the new one to ensure active plugins can still be updated or uninstalled. + +Make sure to also update the Subgraph and SDK to be able to handle both old & new `PluginSetupProcessor` ## Roll-Out From 9b9ca6ef2ed8b182b64c615d553ac2b9a26bc547 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 11:21:08 +0200 Subject: [PATCH 09/19] docs: added information on generic changes from notion --- .../04-framework-lifecycle/02-semver.md | 230 ++++++++++++++++-- 1 file changed, 210 insertions(+), 20 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md index 602583a61..d26ce7c17 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md @@ -14,23 +14,213 @@ We use the semver notation to version the OSx Protocol smart contract and to cla We now classify [smart contract changes](systems.md#smart-contracts) according to SemVer and how they affect the [the subgraph](01-systems.md#the-subgraph), consumers of the contracts and the subgraph such as the [the SDK or 3rd party projects](systems.md#sdk-3rd-party-projects-contract--subgraph-consumers), and [the App](01-systems.md#app). -| SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | -| --------------------- | ------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -| major | storage change | stateful | change, removal | adaptation needed, potential exploits, unexpected behavior | reverting calls, wrong values | reverting calls, wrong values | reverting calls, wrong values | -| major | inheritance | stateful, upgradeable | addition, change, removal | adaptation needed, storage corruption | | | | -| major | event change | logging | change, removal | | adaptation needed, errors | adaptation needed, reverting calls | reverting calls | -| major | external function header change | interface reliant | change, removal | adaptation needed, reverting calls | errors | errors, reverting calls | adaptation needed, errors | -| major | external function removal | interface reliant | removal | adaptation needed, fallback triggering, reverting calls | errors | adaptation needed, errors | adaptation needed, errors | -| major | enum change | | change, removal | potential exploits, reverting calls, unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | -| minor | storage addition | stateful, upgradeable | addition | | | | | -| minor | event addition | | addition | | adaptation needed | adaptation needed | | -| minor | external function addition | | addition | feature addition | | feature addition | feature addition | -| major, minor, patch | external function body change | | change | feature addition | | | | -| minor, patch | internal function | | addition, change, removal | | | | | -| minor, patch | enum addition | | addition | | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | -| patch | custom error | | addition, change, removal | adaptation needed | | adaptation needed | | -| patch | constant/immutable | | addition, change, removal | | | | | -| UNCLEAR | compiler version | | change | adaptation needed | | | | -| | | | | | | | | -| patch | file path | all | change | adaptation needed | adaptation needed | adaptation needed | | -| | | | | | | | | +| SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | +| --------------------- | -------------------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| major | [storage](#storage) change | stateful | change, removal | adaptation needed, potential exploits, unexpected behavior | reverting calls, wrong values | reverting calls, wrong values | reverting calls, wrong values | +| major | [inheritance](#inheritance) | stateful, upgradeable | addition, change, removal | adaptation needed, storage corruption | | | | +| major | [event](#event) change | logging | change, removal | | adaptation needed, errors | adaptation needed, reverting calls | reverting calls | +| major | [external function](#external) header change | interface reliant | change, removal | adaptation needed, reverting calls | errors | errors, reverting calls | adaptation needed, errors | +| major | [external function](#external) removal | interface reliant | removal | adaptation needed, fallback triggering, reverting calls | errors | adaptation needed, errors | adaptation needed, errors | +| major | [enum](#enum) change | | change, removal | potential exploits, reverting calls, unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | +| minor | [storage](#storage) addition | stateful, upgradeable | addition | | | | | +| minor | [event](#event) addition | | addition | | adaptation needed | adaptation needed | | +| minor | [external function](#external) addition | | addition | feature addition | | feature addition | feature addition | +| major, minor, patch | [external function](#external) body change | | change | feature addition | | | | +| minor, patch | [internal function](#internal) | | addition, change, removal | | | | | +| minor, patch | [enum](#enum) addition | | addition | | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | +| patch | [custom error](#custom-error) | | addition, change, removal | adaptation needed | | adaptation needed | | +| patch | [constant/immutable](#constant-or-immutable) | | addition, change, removal | | | | | +| UNCLEAR | [compiler version](#compiler-version) | | change | adaptation needed | | | | +| | | | | | | | | +| patch | [file path](#file-path) | all | change | adaptation needed | adaptation needed | adaptation needed | | +| | | | | | | | | + +### Storage + +- Addition + Be aware that public constatns/immutables affect the `interfaceId``. + Implementation + + - **IF** contract is **NOT** upgradeable + - no action required + - **IF** contract is upgradeable + + - [ ] the storage slot must be strictly appended + - it must be added after all previously declared storage + - **IF** struct in a mapping, the new field must be appended at the end of the struct + - **IF** array, this can break storage **(discovery needed**) + - [ ] the storage gap at the bottom must be reduced + - [ ] double-checked that inheriting contracts are not affected + - [ ] Add default value (if not 0) to initializer + + - [ ] increase the initializer version counter by 1 + - [ ] Double-check that initializer is called by deploy script/update actions + + Testing + + - [ ] write unit tests checking that the storage is set and initialized correctly + - **IF** contract is upgradeable + + - [ ] write regression tests + - [ ] test the storage is not corrupted in the upgrade + - [ ] write integration tests + - [ ] Apply the update on a fork and check that nothing breaks (e.g., use the managing DAO as a testing DAO) + +- Change + + - should be avoided + - exceptions can be in repurposing in controlled scenarios + - e.g., if an `address` variable is used for another purpose after an upgrade is happened, it must be made sure that the variable is brought into a controlled state, e.g. is immediately initialized with `initializeFrom`/`upgradeToAndCall` + +- Removal + + - must never happen + + - this will shift down the storage layout and can lead to unexpected behavior and potential exploits + + - exception is explicit deprecation + +The reordering / removal of fields in structs being stored in dynamic arrays or mappings (that are stored as a hashtable) corrupt the hash table entries, not subsequent storage in the contract slot. More discovery is needed here. + +### Inheritance + +- not easily possible if the base class introduces storage and therefore needs a storage gap itself, which is likely the case + - new contract needs to inherit from the previous implementation + - methods affected must be virtual to be overriden + - initialization gets convoluted + - the double initialization problem must be avoided + +See the [OpenZeppelin article on multiple inheritance](https://docs.openzeppelin.com/contracts/4.x/upgradeable#multiple-inheritance). + +### Function + +#### External + +- Addition + + - **IF** used by SDK + + - [ ] adapt SDK + + - **IF** used by App + - [ ] adapt App + +- Change + + - Body + A change to a function body can change the behaviour of the function requiring dependent contracts or software systems to change + + - **IF** used by SDK + + - [ ] adapt SDK + + - **IF** used by App + - [ ] adapt App + + Behavioural changes that can be **major** / breaking + + - additional checks that result in external contracts reverting + - making different internal or external calls + - different execution or storing logic + + Behavioural changes that can be **minor** + + - storing new values + + Non-behavioural changes that classify as **patch** + + - gas optimizations + + - logic simplification + + - Header + - this changes the function signature + - this changes the interface of the contract and its `interfaceId` + - if the contract supports ERC-165, the new version will not be recognized anymore + - every contract that needs to detect it must adapt and be upgraded / redeployed + +- Removal + + - this changes the interface of the contract and its `interfaceId` + - if an external contract uses this external function, it breaks + - if the contract supports ERC-165, the new version will not be recognized anymore + + - every contract that needs to detect it must adapt and be upgraded / redeployed + + - changes in depending software systems + - other, relying or managing OSx contracts + - SDK + - subgraph + - App + +#### Internal + +Similar to an [external function body change](#external) change, a change to a function body can alter the behavior of the function. +Inheriting contracts or depending software systems must adapt. + +### Event + +- Addition + + - [ ] adapt subgraph handler function + - [ ] write subgraph tests + - **IF** the contracts is upgradable + +- Change + + - [ ] add the new fields / entities and listen to the same address + - [ ] adapt depending software so that it can handle entities in which the field is not set yet + + - **IF** the contract is **NOT** upgradeable + - a new contract must be deployed + - old instances still in use will still emit the old event + - the subgraph needs to listen to both contracts + - **IF** used by SDK + - [ ] adapt SDK + +- Renaming + This can happen when we find a typo in the name or have to rename it for standardization purposes + - [ ] adapt subgraph to handle new function name + - [ ] change SDK to parse with the correct ABI + +### Enum + +- Addition + + - enum declarations do NOT affect the interface + + - **IF** used by SDK + + - [ ] adapt SDK + + - **IF** used by App + - [ ] adapt App + +- Change + - enum declarations do NOT affect the interface + - depending code logic might change / break if: + - the enum items order is changed or items are removed + - Enum order changes can open vulnerabilities because values set represent a different value/meaning + - Enums used as keys in mappings or arrays shouldn’t be allowed to be changed + - the enum is deleted + +### Custom Error + +**IF** these errors affect the behavior or the SDK / App handles these errors, the respective components must adapt. + +### Constant or Immutable + +Logic using the constants / immutable variables must be adapted + +Be aware that public constatns/immutables change the `interfaceId`. + +### Compiler Version + +This can be caused by vulnerability being detected in an earlier version https://docs.soliditylang.org/en/latest/bugs.html or new features being introduced. + +- the contracts affected by the vulnerability must be redeployed +- depending on the pragma change, this can cause incompatibilities with other internal or external contracts + +### File Path + +Inheriting contracts must use the new file path. From 55aa9ba04f678fde4ce5245db290c894099e08a5 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 11:28:10 +0200 Subject: [PATCH 10/19] docs: removed todo and fixed formatting --- .../03-osx-components/07-plugin-setup.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md index fbb15c914..2876f660c 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md @@ -1,9 +1,5 @@ # Plugin Setup -:::todo -PAGE IS WORK IN PROGRESS -::: - ```mermaid flowchart TD processStart("Publish a PluginSetup") @@ -73,14 +69,15 @@ Conduct all necessary actions to prepare the uninstallation of a plugin and to d - decode `_payload._data` if required - return initialization data to be used with `upgradeToAndCall` - transition + - the `SetupPayload.plugin` contract - `SetupPayload.currentHelpers` contracts - and existing permission -over from the `_currentBuild` to the new build by + over from the `_currentBuild` to the new build by -- deploying / decomissioning helpers return the addresses of the prevailing ones via the `preparedSetupData.helpers` array of addresses. -- requesting to grant new / revoke existing permissions and returning them via the `preparedSetupData.permissions` array of permission structs. + - deploying / decomissioning helpers return the addresses of the prevailing ones via the `preparedSetupData.helpers` array of addresses. + - requesting to grant new / revoke existing permissions and returning them via the `preparedSetupData.permissions` array of permission structs. ## Update Metadata From 33b3c52c3ce5117093bb148622f50b3552c2397a Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 11:28:20 +0200 Subject: [PATCH 11/19] docs: added contract overview --- .../03-osx-components/aragon-osx.svg | 1 + .../03-osx-components/index.md | 56 +++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/aragon-osx.svg create mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/aragon-osx.svg b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/aragon-osx.svg new file mode 100644 index 000000000..9f58c8dd6 --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/aragon-osx.svg @@ -0,0 +1 @@ +IPluginIPluginSetupIDAOPluginSetupProcessorPluginRepoFactoryPluginRepoPluginRepoRegistryPermissionManagerPluginSetupPluginDAODAOFactoryDAORegistry+registers*1***111+registers+deploysProxy+deploys proxy+applySetupCallbackHandlerIMembersipIProposalDaoAuthorizable+consumes+pluginTypeIPluginRepoInterfaceBasedRegistryENSSubdomainRegistrarIPermissionConditionProposal+createDao+asks \ No newline at end of file diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md new file mode 100644 index 000000000..8a44f06ad --- /dev/null +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md @@ -0,0 +1,56 @@ +# Contracts of Aragon OSX + +
+ +![UML diagram of Aragon OSx contracts and their internal dependencies.](aragon-osx.svg) + +

+ UML diagram of Aragon OSx contracts and their internal dependencies. +

+ +
+ +## Interfaces + +- `IDAO` +- `IPlugin` +- `IPluginSetup` +- `IPluginRepo` +- `IPermissionCondition` +- `IProposal` +- `IMembership` + +## Abstract Contracts + +### Non-Upgradable + +- `DaoAuthorizable` +- `Proposal` +- `CallbackHandler` +- `PermissionManager` +- `Plugin` +- `PluginCloneable` +- `PluginSetup` + +### Upgradeable + +- `DaoAuthorizableUpgradeable` +- `ProposalUpgradeable` +- `InterfaceBasedRegistry` + +## Deployed Contracts + +### Non-Upgradable + +- `DAOFactory` +- `PluginRepoFactory` +- `PluginSetupProcessor` + +### Upgradeable + +- `DAO` +- `DAORegistry` +- `PluginRepo` +- `PluginRepoRegistry` +- `PluginUUPSUpgradeable` +- `ENSSubdomainRegistrar` From 094cdd8976f0c27d86998b562664bc8bcfb4e188 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 12:14:21 +0200 Subject: [PATCH 12/19] docs: remove redundant text --- .../03-osx-components/00-abstract-contract.md | 7 ------- .../03-osx-components/01-factory-contract.md | 14 +++++++------- .../03-osx-components/02-upgradeable-contract.md | 5 ----- 3 files changed, 7 insertions(+), 19 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md index 98815546b..476241805 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md @@ -1,12 +1,5 @@ # Abstract Contract Change -Applies to: - -- `PermissionManager` -- `CallbackHandler` -- `DaoAuthorizable` and `DaoAuthorizableUpgradeable` -- `Proposal` and `ProposalUpgradeable` - ```mermaid flowchart TD processStart("Abstract Contract Change") diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md index bd983d602..31de5e164 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -1,12 +1,5 @@ # Factory Change -Applies to - -- `DAOFactory` -- `PluginRepoFactory` - -For changes in the underlying implementations (i.e., `DAO` and `PluginRepo`), see the process of [replacing upgradeable contracts](../03-sub-processes/upgradeable-contract.md). - ```mermaid flowchart TD processStart("Factory Change") @@ -67,3 +60,10 @@ flowchart TD rollout ==> processEnd("Done") ``` + +Applies to + +- `DAOFactory` +- `PluginRepoFactory` + +For changes in the underlying implementations (i.e., `DAO` and `PluginRepo`), see the process of [replacing upgradeable contracts](../03-sub-processes/upgradeable-contract.md). diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md index 98f393f3b..2df8af0ac 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md @@ -1,10 +1,5 @@ # UUPS Upgradeable Contract Change -Applies to - -- `DAO` -- `PluginRepo` - ```mermaid flowchart TD processStart("UUPS upgradeable contract") From ad9f58d10ae94fef9ed2f0c894070c88c858afa9 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 12:25:37 +0200 Subject: [PATCH 13/19] docs: remove duplication --- .../04-sub-processes/01-protocol-version.md | 37 +------------------ 1 file changed, 1 insertion(+), 36 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md index f9b55a769..bf1652244 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md @@ -18,39 +18,4 @@ flowchart TD adaptInitializeFrom --> processEnd("Done") ``` -## Semantic Versioning - -We use the semver notation to version the OSx Protocol smart contract and to classify changes into MAJOR, MINOR, or PATCH. - -> Given a version number MAJOR.MINOR.PATCH, increment the: -> -> 1. MAJOR version when you make incompatible API changes -> 2. MINOR version when you add functionality in a backwards compatible manner -> 3. PATCH version when you make backwards compatible bug fixes - -### Change Classifications - -We now classify [smart contract changes](../01-systems.md#smart-contracts) according to SemVer and how they affect - -- [The subgraph](../01-systems.md#the-subgraph) -- [the SDK or 3rd party projects](../01-systems.md#sdk-3rd-party-projects-contract--subgraph-consumers) consuming the contracts and the subgraph -- [the App](../01-systems.md#app) - -| SemVer Classification | Change in | Affected contracts | Action | Contract Implication (OSx or 3rd party) | Subgraph | SDK | App | -| --------------------- | ------------------------------- | --------------------- | ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -| major | storage change | stateful | change, removal | adaptation needed, potential exploits, unexpected behavior | reverting calls, wrong values | reverting calls, wrong values | reverting calls, wrong values | -| major | inheritance | stateful, upgradeable | addition, change, removal | adaptation needed, storage corruption | | | | -| major | event change | logging | change, removal | | adaptation needed, errors | adaptation needed, reverting calls | reverting calls | -| major | external function header change | interface reliant | change, removal | adaptation needed, reverting calls | errors | errors, reverting calls | adaptation needed, errors | -| major | external function removal | interface reliant | removal | adaptation needed, fallback triggering, reverting calls | errors | adaptation needed, errors | adaptation needed, errors | -| major | enum change | | change, removal | potential exploits, reverting calls, unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | unexpected behavior, wrong values | -| minor | storage addition | stateful, upgradeable | addition | | | | | -| minor | event addition | | addition | | adaptation needed | adaptation needed | | -| minor | external function addition | | addition | feature addition | | feature addition | feature addition | -| major, minor, patch | external function body change | | change | feature addition | | | | -| minor, patch | internal function | | addition, change, removal | | | | | -| minor, patch | enum addition | | addition | | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | adaptation needed, errors, fallback triggering, wrong values | -| patch | custom error | | addition, change, removal | adaptation needed | | adaptation needed | | -| patch | constant/immutable | | addition, change, removal | | | | | -| patch | compiler version | | change | adaptation needed | | | | -| patch | file path | all | change | adaptation needed | adaptation needed | adaptation needed | | +To asses what changes justify a MAJOR, MINOR, or PATCH version number bump, see the page on [SemVer Classification of OSx Contract Changes](../02-semver.md). From 875fdaf3bea27286661fe8f3f674873cceb561ac Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 12:26:30 +0200 Subject: [PATCH 14/19] docs: fix wrong comparator --- .../04-sub-processes/02-contract-initialization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md index 91e54e867..50e64bc98 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md @@ -96,19 +96,19 @@ function initializeFrom( // Everybody will have at least a v1.0.0 contract initialized so we don't need to check for `_previousProtocolVersion.lte([1, 0, 0])` - if (_previousProtocolVersion.lte([1, 0, 1])) { + if (_previousProtocolVersion.lt([1, 0, 1])) { internalCallB(); } - if (_previousProtocolVersion.lte([1, 1, 0])) { + if (_previousProtocolVersion.lt([1, 1, 0])) { c = _c; } - if (_previousProtocolVersion.lte([1, 1, 1])) { + if (_previousProtocolVersion.lt([1, 1, 1])) { emit EventD(); } - if (_previousProtocolVersion.lte([1, 2, 0])) { + if (_previousProtocolVersion.lt([1, 2, 0])) { externalCallE(); emit EventE(); } From 9339739bd07ffaf11d663ee2f4927c0e03aaa3e2 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 12:29:38 +0200 Subject: [PATCH 15/19] docs: remove outdated todo --- .../04-sub-processes/02-contract-initialization.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md index 50e64bc98..ad82efbc9 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/02-contract-initialization.md @@ -121,7 +121,3 @@ If we now upgrade from the previous version `1.0.1` to `1.2.0`, we would apply t - `1.1.1` Written this way, the `initializeFrom` function ensures that all initializations that have happened in between the two versions are applied. - -:::todo -We have to implement the less than comparator `function lte(uint[3] memory lhs, uint[3] memory rhs) internal pure returns (bool)`. -::: From a1ddb1ea4ee954f192886d1fa335d0c932ef5b9a Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 12:30:22 +0200 Subject: [PATCH 16/19] docs: whitespace --- .../04-framework-lifecycle/04-sub-processes/03-testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md index a97445f8c..96665f3d3 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/03-testing.md @@ -42,6 +42,6 @@ This might include: - checks for storage corruption - checks for reinitializer number bumps - fork tests against currently active contracts (to ensure that interfaces and functionalities match with each other) such as - - the`PluginSetupProcessor` + - the `PluginSetupProcessor` - `PluginRepo`s - - .... + - ... From c04f4beff3c3a1430b48bfc7aafd228fd3314088 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 13:21:04 +0200 Subject: [PATCH 17/19] docs: rearrange systems page --- .../04-framework-lifecycle/01-systems.md | 75 +++++++++++++++++-- .../04-framework-lifecycle/02-semver.md | 2 +- .../03-osx-components/index.md | 56 -------------- .../{03-osx-components => }/aragon-osx.svg | 0 4 files changed, 70 insertions(+), 63 deletions(-) delete mode 100644 packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md rename packages/contracts/docs/developer-portal/04-framework-lifecycle/{03-osx-components => }/aragon-osx.svg (100%) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md index 37a944eae..f23d3a726 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md @@ -1,6 +1,6 @@ -# Software Systems Running the Aragon OSx +# Software Systems of Aragon OSx -## Smart Contracts +## Contracts Ethereum smart contracts are created at compile time @@ -25,7 +25,70 @@ During run time, the successful execution of transactions with construction / initialization constituting a special. -## The Subgraph +## Contracts of Aragon OSX + +
+ +![UML diagram of Aragon OSx contracts and their internal dependencies.](aragon-osx.svg) + +

+ UML diagram of Aragon OSx contracts and their internal dependencies. +

+ +
+ +
Interfaces + +- `IDAO` +- `IPlugin` +- `IPluginSetup` +- `IPluginRepo` +- `IPermissionCondition` +- `IProposal` +- `IMembership` + +
+ +
Abstract Contracts + +- Non-Upgradable + + - `DaoAuthorizable` + - `Proposal` + - `CallbackHandler` + - `PermissionManager` + - `Plugin` + - `PluginCloneable` + - `PluginSetup` + +- Upgradeable + + - `DaoAuthorizableUpgradeable` + - `ProposalUpgradeable` + - `InterfaceBasedRegistry` + +
+ +
Deployed Contracts + +- Non-Upgradable + + - `DAOFactory` + - `PluginRepoFactory` + - `PluginSetupProcessor` + +- Upgradeable + + - `DAO` + - `DAORegistry` + - `PluginRepo` + - `PluginRepoRegistry` + - `PluginUUPSUpgradeable` + - `ENSSubdomainRegistrar` + +
+ +## Subgraph The subgraph is composed of @@ -43,9 +106,9 @@ OSx contract changes being relevant are: Addition of an event is a compatible change, whereas all other changes are incompatible and force the subgraph to adapt. -## SDK, 3rd-Party Projects (Contract & Subgraph Consumers) +## Aragon SDK, 3rd-Party Projects (Contract & Subgraph Consumers) -The SDK (as well as 3rd-party projects) queries the subgraph and interacts with the deployed contract’s ABI. +The SDK as well as 3rd-party projects query the subgraph and interact with the deployed contract’s ABI. OSx contract changes being relevant are: @@ -68,7 +131,7 @@ If these changes happen on plugin-related components, i.e., this affects integrators of the protocol. -## App +## Aragon App The App queries the subgraph and uses the SDK to interact with the contracts. In some cases, it makes direct calls to contracts provided by us or third parties. diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md index d26ce7c17..daf25618e 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/02-semver.md @@ -38,7 +38,7 @@ We now classify [smart contract changes](systems.md#smart-contracts) according t ### Storage - Addition - Be aware that public constatns/immutables affect the `interfaceId``. + Be aware that public constatns/immutables affect the `interfaceId`. Implementation - **IF** contract is **NOT** upgradeable diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md deleted file mode 100644 index 8a44f06ad..000000000 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/index.md +++ /dev/null @@ -1,56 +0,0 @@ -# Contracts of Aragon OSX - -
- -![UML diagram of Aragon OSx contracts and their internal dependencies.](aragon-osx.svg) - -

- UML diagram of Aragon OSx contracts and their internal dependencies. -

- -
- -## Interfaces - -- `IDAO` -- `IPlugin` -- `IPluginSetup` -- `IPluginRepo` -- `IPermissionCondition` -- `IProposal` -- `IMembership` - -## Abstract Contracts - -### Non-Upgradable - -- `DaoAuthorizable` -- `Proposal` -- `CallbackHandler` -- `PermissionManager` -- `Plugin` -- `PluginCloneable` -- `PluginSetup` - -### Upgradeable - -- `DaoAuthorizableUpgradeable` -- `ProposalUpgradeable` -- `InterfaceBasedRegistry` - -## Deployed Contracts - -### Non-Upgradable - -- `DAOFactory` -- `PluginRepoFactory` -- `PluginSetupProcessor` - -### Upgradeable - -- `DAO` -- `DAORegistry` -- `PluginRepo` -- `PluginRepoRegistry` -- `PluginUUPSUpgradeable` -- `ENSSubdomainRegistrar` diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/aragon-osx.svg b/packages/contracts/docs/developer-portal/04-framework-lifecycle/aragon-osx.svg similarity index 100% rename from packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/aragon-osx.svg rename to packages/contracts/docs/developer-portal/04-framework-lifecycle/aragon-osx.svg From c726cb7f78b604327c5ab99c3c0c5c092af7f0f5 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Thu, 12 Oct 2023 13:21:45 +0200 Subject: [PATCH 18/19] docs: fix header --- .../docs/developer-portal/04-framework-lifecycle/01-systems.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md index f23d3a726..b90e7ea7a 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/01-systems.md @@ -25,7 +25,7 @@ During run time, the successful execution of transactions with construction / initialization constituting a special. -## Contracts of Aragon OSX +### Aragon OSX
From fd039451a1cb1715a185e475fc04377c1de785d2 Mon Sep 17 00:00:00 2001 From: Michael Heuer Date: Mon, 23 Oct 2023 09:54:20 +0200 Subject: [PATCH 19/19] docs: fix links Co-authored-by: Aaron Abu Usama <50079365+pythonpete32@users.noreply.github.com> --- .../03-osx-components/00-abstract-contract.md | 6 +++--- .../03-osx-components/01-factory-contract.md | 11 ++++++----- .../03-osx-components/02-upgradeable-contract.md | 10 +++++----- .../03-osx-components/03-non-upgradeable-contract.md | 10 +++++----- .../03-osx-components/04-registry-contract.md | 8 ++++---- .../03-osx-components/05-plugin-setup-processor.md | 6 +++--- .../03-osx-components/06-plugin-build.md | 12 ++++++------ .../03-osx-components/07-plugin-setup.md | 6 +++--- .../04-sub-processes/01-protocol-version.md | 2 +- 9 files changed, 36 insertions(+), 35 deletions(-) diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md index 476241805..24534f3b1 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/00-abstract-contract.md @@ -10,7 +10,7 @@ flowchart TD upgradeableContractImplementation[[UUPS upgradeable \n contract change]] nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] affectsInitialization{"affects \n initialization?"} - adaptInitialization[[" adapt initialization\n in inheriting contract"]] + adaptInitialization[[" adapt initialization\n in inheriting contract"]] bumpProtocolVersion --> isUpgradeable isUpgradeable -->|yes| upgradeableContractImplementation --> affectsInitialization @@ -18,12 +18,12 @@ flowchart TD affectsInitialization -->|yes| adaptInitialization end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md index 31de5e164..4ad8f92d0 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/01-factory-contract.md @@ -8,7 +8,7 @@ flowchart TD subgraph implementation[Implementation] %% Standard Checks - bumpProtocolVersion[["Bump protocol version"]] + bumpProtocolVersion[["Bump protocol version"]] isBaseChange{"is base imple- \n mentation change?"} %% Actions @@ -25,13 +25,14 @@ flowchart TD end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] + + testing ==> docs[[Documentation]] - testing ==> docs[[Documentation]] docs ==> deployment subgraph deployment[Deployment] - deployContract[[standard deployment process]] + deployContract[[standard deployment process]] deployContract --> managingDaoProposal subgraph managingDaoProposal["Managing DAO Proposal"] @@ -53,7 +54,7 @@ flowchart TD affectsApp -->|yes| appUpdate --> announceUpdate affectsApp -->|no| announceUpdate - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] announceUpdate end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md index 2df8af0ac..dd3d6c7af 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/02-upgradeable-contract.md @@ -12,7 +12,7 @@ flowchart TD adaptSubgraph[["adapt subgraph"]] affectsInitialization{"affects \n initialization?"} - adaptInitialization[[" adapt initialization"]] + adaptInitialization[[" adapt initialization"]] affectsStorageGaps -->|no| affectsSubgraph affectsStorageGaps -->|yes| adaptStorageGaps @@ -26,11 +26,11 @@ flowchart TD affectsInitialization -->|yes| adaptInitialization end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] - docs ==> deployment[[Deployment]] + docs ==> deployment[[Deployment]] deployment ==> rollout subgraph rollout[Roll-out] @@ -45,7 +45,7 @@ flowchart TD affectsApp -->|yes| appUpdate --> announceUpdate affectsApp -->|no| announceUpdate - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] announceUpdate --> initializationChange initializationChange{"initialization \n change?"} diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md index aeda20502..82b63eaab 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/03-non-upgradeable-contract.md @@ -10,7 +10,7 @@ flowchart TD adaptSubgraph[["adapt subgraph"]] affectsInitialization{"affects \n initialization?"} - adaptInitialization[[" adapt initialization"]] + adaptInitialization[[" adapt initialization"]] affectsSubgraph -->|no| affectsInitialization affectsSubgraph -->|yes| adaptSubgraph @@ -19,11 +19,11 @@ flowchart TD affectsInitialization -->|yes| adaptInitialization end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] - docs ==> deployment[[Deployment]] + docs ==> deployment[[Deployment]] deployment ==> rollout subgraph rollout[Roll-out] @@ -35,7 +35,7 @@ flowchart TD appUpdate["update App"] affectsApp{"affects App?"} - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] affectsApp -->|yes| appUpdate --> announceUpdate affectsApp -->|no| announceUpdate end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md index d81907984..b1a4e23a1 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/04-registry-contract.md @@ -10,17 +10,17 @@ flowchart TD processStart("Registry change") processStart ==> implementation subgraph implementation[Implementation] - bumpProtocolVersion[["Bump protocol version"]] - upgradeableContractImplementation[[UUPS upgradeable contract \n change]] + bumpProtocolVersion[["Bump protocol version"]] + upgradeableContractImplementation[[UUPS upgradeable contract \n change]] bumpProtocolVersion --> upgradeableContractImplementation end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md index e36c32620..daf53a571 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/05-plugin-setup-processor.md @@ -5,15 +5,15 @@ flowchart TD processStart("PluginSetupProcessor change") processStart ==> implementation subgraph implementation[Implementation] - nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] ensureCompatibility["ensure backwards compat- \n ibility with active setups"] nonUpgradeableContractImplementation --> ensureCompatibility end - implementation ==> testing[Testing] + implementation ==> testing[Testing] - testing ==> docs[Documentation] + testing ==> docs[Documentation] docs ==> deployment subgraph deployment[Deployment] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md index 85ffd2ed9..fadba3a96 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/06-plugin-build.md @@ -6,19 +6,19 @@ flowchart TD processStart ==> implementation subgraph implementation[Implementation] isUpgradeable{"is UUPS \n upgradeable?"} - upgradeableContractImplementation[[UUPS upgradeable \n contract change]] - nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] - adaptPluginSetup[[implement PluginSetup]] + upgradeableContractImplementation[[UUPS upgradeable \n contract change]] + nonUpgradeableContractImplementation[[non-upgradeable \n contract change]] + adaptPluginSetup[[implement PluginSetup]] isUpgradeable -->|yes| upgradeableContractImplementation --> adaptPluginSetup isUpgradeable -->|no| nonUpgradeableContractImplementation --> adaptPluginSetup end - implementation ==> testing[Testing] + implementation ==> testing[Testing] %%subgraph testing[Testing] %%end - testing ==> docs[Documentation] + testing ==> docs[Documentation] %%subgraph testing[Testing] %%end @@ -29,7 +29,7 @@ flowchart TD deployment ==> rollout subgraph rollout[Roll-out] - publishPluginSetup[[publish PluginSetup]] + publishPluginSetup[[publish PluginSetup]] end rollout ==> processEnd("Done") diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md index 2876f660c..f5059cc71 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/03-osx-components/07-plugin-setup.md @@ -17,11 +17,11 @@ flowchart TD isUpgradeable -->|no| updateMetadata end - implementation ==> testing[[Testing]] + implementation ==> testing[[Testing]] %%subgraph testing[Testing] %%end - testing ==> docs[[Documentation]] + testing ==> docs[[Documentation]] %%subgraph testing[Testing] %%end @@ -34,7 +34,7 @@ flowchart TD subgraph rollout[Roll-out] isAragonPlugin{"is Aragon \n plugin?"} managingDaoProposal["management DAO \n proposal"] - announceUpdate[["announce Aragon update"]] + announceUpdate[["announce Aragon update"]] publishToAragonPluginRepo["publish PluginSetup \n in Aragon PluginRepo"] publishToPluginRepo["publish PluginSetup \n in 3rd-party repo"] diff --git a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md index bf1652244..c9a4a8a2e 100644 --- a/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md +++ b/packages/contracts/docs/developer-portal/04-framework-lifecycle/04-sub-processes/01-protocol-version.md @@ -7,7 +7,7 @@ flowchart TD bumpProtocolVersion["Bump the global \n ProtocolVersion number"] mostDerivedCheck["Check that all most derived contracts \n inherit from the ProtocolVersion contract"] - adaptInitializeFrom[["adapt the initializeFrom() \n function of affected contracts"]] + adaptInitializeFrom[["adapt the initializeFrom() \n function of affected contracts"]] processStart --> bumpProtocolVersion