feat: improved update checklist (#396)

* feat: improved update checklist

* feat: update PR checklist

* feat: improved the update checklist

* fix: remove checklist item

* feat: added publishing flow by Jordi

* chore: Updates update_checklist to reflect multiple version
The checkslist allows version specific tasks in a append only format

* feat: formatting

* fix: typo

* feat: restructure README section about publication

* revert: re-formatting

* fix: wrong link

---------

Co-authored-by: Mathias Scherer <[email protected]>

.github/pull_request_template.md

@@ -21,5 +21,6 @@ Task: [ID]()
 - [ ] My changes generate no new warnings.
 - [ ] Any dependent changes have been merged and published in downstream modules.
 - [ ] I ran all tests with success and extended them if necessary.
-- [ ] I have updated the ``CHANGELOG.md`` file in the root folder.
-- [ ] I have tested my code on the test network.
+- [ ] I have updated the `CHANGELOG.md` file in the root folder.
+- [ ] I have updated the `DEPLOYMENT_CHECKLIST` file in the root folder.
+- [ ] I have updated the `UPDATE_CHECKLIST` file in the root folder.

README.md

@@ -5,11 +5,13 @@
 The Aragon OSx protocol is the foundation layer of the new Aragon stack. It allows users to create, manage, and customize DAOs in a way that is lean, adaptable, and secure.
 
 Within this monorepo, you will be able to find 3 individual packages:
+
 - [Contracts](https://github.com/aragon/osx/tree/develop/packages/contracts): the Aragon OSx protocol contracts.
 - [Subgraph](https://github.com/aragon/osx/tree/develop/packages/subgraph): contains all code generating our subgraph and event indexing.
 - [Contract-ethers](https://github.com/aragon/osx/tree/develop/packages/contracts-ethers): contains the connection between the ethers package and our contracts.
 
 The contents of this repository are distributed via 3 different NPM packages:
+
 - `@aragon/osx`: The source files, including the protocol contracts and interfaces
 - `@aragon/osx-artifacts`: The contracts bytecode and ABI to use the protocol or deploy it
 - `@aragon/osx-ethers`: The TypeScript wrappers to use the protocol or deploy it using ethers.js
@@ -18,7 +20,7 @@ For more information on the individual packages, please read the respective `REA
 
 ## Audit
 
-The core smart contracts have been audited by [Halborn](https://www.halborn.com/). 
+The core smart contracts have been audited by [Halborn](https://www.halborn.com/).
 
 - [Security audit report](./audits/AragonOSx-security-audit-report-halborn.pdf)
 - The commit ID: [cb0621dc5185a73240a6ca33fccc7698f059fdf5](https://github.com/aragon/osx/commit/cb0621dc5185a73240a6ca33fccc7698f059fdf5)
@@ -42,43 +44,43 @@ To review the contracts powering the Aragon OSx protocol, feel free to head to `
 
 The Aragon OSx protocol architecture is composed of two key sections:
 
-- __Core contracts__: the primitives the end user will interact with. It is composed of mostly 3 parts:
-    - **DAO contract:** the main contract of our core. It holds a DAO's assets and possible actions.
-    - **Permissions**: govern interactions between the plugins, DAOs, and any other address - allowing them (or not) to execute actions on behalf of and within the DAO.
-    - **Plugins**: base templates of plugins to build upon.
-- __Framework contracts__: in charge of creating and registering each deployed DAO or plugin. It contains:
-    - **DAO and Plugin Repository Factories**: creates DAOs or plugins.
-    - **DAO and Plugin Registries**: registers into our protocol those DAOs or plugins.
-    - **Plugin Setup Processor:** installs and uninstalls plugins into DAOs.
+- **Core contracts**: the primitives the end user will interact with. It is composed of mostly 3 parts:
+  - **DAO contract:** the main contract of our core. It holds a DAO's assets and possible actions.
+  - **Permissions**: govern interactions between the plugins, DAOs, and any other address - allowing them (or not) to execute actions on behalf of and within the DAO.
+  - **Plugins**: base templates of plugins to build upon.
+- **Framework contracts**: in charge of creating and registering each deployed DAO or plugin. It contains:
+  - **DAO and Plugin Repository Factories**: creates DAOs or plugins.
+  - **DAO and Plugin Registries**: registers into our protocol those DAOs or plugins.
+  - **Plugin Setup Processor:** installs and uninstalls plugins into DAOs.
 
 Additionally to those two sections, we have developed several plugins DAOs can easily install upon creation. These are:
 
-- __Token Voting plugin__: enables token holders to vote yes, no or abstain on incoming DAO proposals
-- __Multisig plugin__: enables DAO governance based on approval from a pre-defined members list.
-- __Addresslist Voting plugin__: enables a pre-defined set of addresses to vote yes, no or abstain in a "one address, one vote" mode
-- __Admin plugin__: enables full access to an account needing to perform initial maintenance tasks without unnecessary overhead
+- **Token Voting plugin**: enables token holders to vote yes, no or abstain on incoming DAO proposals
+- **Multisig plugin**: enables DAO governance based on approval from a pre-defined members list.
+- **Addresslist Voting plugin**: enables a pre-defined set of addresses to vote yes, no or abstain in a "one address, one vote" mode
+- **Admin plugin**: enables full access to an account needing to perform initial maintenance tasks without unnecessary overhead
 
 Let's dive into more detail on each of these sections.
 
 ### Core Contracts
 
-The *Core Contracts* describe how every DAO generated by the Aragon OSx protocol will be set up. It is very lean by design and constitutes the most critical aspects of our architecture.
+The _Core Contracts_ describe how every DAO generated by the Aragon OSx protocol will be set up. It is very lean by design and constitutes the most critical aspects of our architecture.
 
 In a nutshell, each DAO is composed of 3 interconnecting components:
 
 1. **The DAO contract:** The DAO contract is where the **core functionality** of the DAO lies. It is the contract in charge of:
-    - Representing the identity and metadata of the DAO (ENS name, logo, description, other metadata)
-    - Holding and managing the treasury assets
-    - Executing arbitrary actions to:
-        - transfer assets
-        - call its own functions
-        - call functions in external contracts
-    - Providing general technical utilities like callback handling and others
+   - Representing the identity and metadata of the DAO (ENS name, logo, description, other metadata)
+   - Holding and managing the treasury assets
+   - Executing arbitrary actions to:
+     - transfer assets
+     - call its own functions
+     - call functions in external contracts
+   - Providing general technical utilities like callback handling and others
 2. **Permissions:** Permissions are an integral part of any DAO and the center of our protocol architecture. The Permissions manager **manages permissions for the DAO** by specifying which addresses have permission to call distinct functions on contracts associated with your DAO. This Permissions manager lives inside the DAO contract.
-3. **Plugins**: Any custom functionality can be added or removed through plugins, allowing you to **fully customize your DAO**. You'll find some base templates of plugins within the `plugins` folder of the *Core Contracts*. Some examples of plugins that DAOs could install are:
-    - Governance (e.g., token voting, one-address one-vote)
-    - Asset management (e.g., ERC-20 or NFT minting, token streaming, DeFi)
-    - Membership (governing budget allowances, access gating, curating a member list)
+3. **Plugins**: Any custom functionality can be added or removed through plugins, allowing you to **fully customize your DAO**. You'll find some base templates of plugins within the `plugins` folder of the _Core Contracts_. Some examples of plugins that DAOs could install are:
+   - Governance (e.g., token voting, one-address one-vote)
+   - Asset management (e.g., ERC-20 or NFT minting, token streaming, DeFi)
+   - Membership (governing budget allowances, access gating, curating a member list)
 
 The following graphic shows an exemplary DAO setup:
 
@@ -88,23 +90,23 @@ An examplary DAO setup showing interactions between the three core contract piec
 
 ### Framework Contracts
 
-In contrast, the *Framework Contracts* are in charge of creating and registering DAOs and plugins. Additionally, these contracts contain the `PluginSetupProcessor` which installs, uninstalls, and updates plugins into DAOs upon request.
+In contrast, the _Framework Contracts_ are in charge of creating and registering DAOs and plugins. Additionally, these contracts contain the `PluginSetupProcessor` which installs, uninstalls, and updates plugins into DAOs upon request.
 
-- __Factories and Registries__
-    - **The DAO Factory**: In charge of deploying instances of a new DAO based on the parameters given, including which plugins to install and additional metadata the DAO has (like a name, description, etc).
-    - **The DAO Registry**: In charge of registering DAOs into our protocol so plugins can easily access all DAO instances within our protocol. It is also in charge of giving DAOs subdomains for easier access.
-    - **The Plugin Factory**: A `PluginRepo` is the repository of versions for a given plugin. The `PluginRepoFactory` contract creates a `PluginRepo` instance for each plugin, so that plugins can update their versioning without complexity in a semantic way similar to the App Store.
-    - **The Plugin Registry**: In charge of registering the `PluginRepo` addresses into our protocol so that DAOs can access all plugins published in the protocol.
-- __Plugin Setup Processor__: The processor is the manager for plugins. It installs, uninstalls, and upgrades plugins for DAOs based on the instructions provided by the plugin setup.
+- **Factories and Registries**
+  - **The DAO Factory**: In charge of deploying instances of a new DAO based on the parameters given, including which plugins to install and additional metadata the DAO has (like a name, description, etc).
+  - **The DAO Registry**: In charge of registering DAOs into our protocol so plugins can easily access all DAO instances within our protocol. It is also in charge of giving DAOs subdomains for easier access.
+  - **The Plugin Factory**: A `PluginRepo` is the repository of versions for a given plugin. The `PluginRepoFactory` contract creates a `PluginRepo` instance for each plugin, so that plugins can update their versioning without complexity in a semantic way similar to the App Store.
+  - **The Plugin Registry**: In charge of registering the `PluginRepo` addresses into our protocol so that DAOs can access all plugins published in the protocol.
+- **Plugin Setup Processor**: The processor is the manager for plugins. It installs, uninstalls, and upgrades plugins for DAOs based on the instructions provided by the plugin setup.
 
 For a more detailed description of each of these components, please visit our [Developer Portal](https://devs.aragon.org).
 
 ### Plugins
 
 Each plugin consists of two key components:
 
-- __The Plugin Logic__: contains the logic for each plugin; the main functionality the plugin extends for the DAO. Can be linked to other helper contracts if needed.
-- __The Plugin Setup__: contains the installation, uninstallation, and upgrade instructions for a plugin into a DAO.
+- **The Plugin Logic**: contains the logic for each plugin; the main functionality the plugin extends for the DAO. Can be linked to other helper contracts if needed.
+- **The Plugin Setup**: contains the installation, uninstallation, and upgrade instructions for a plugin into a DAO.
 
 You can find all plugins built by the Aragon team [here](https://github.com/aragon/osx/tree/develop/packages/contracts/src/plugins).
 
@@ -150,7 +152,38 @@ npx solhint 'contracts/**/*.sol' --fix
 
 You can find more details about [our deployment checklist here](https://github.com/aragon/osx/blob/develop/DEPLOYMENT_CHECKLIST.md).
 
-## Releasing
+## Publishing protocol upgrades
+
+**Testnets**
+
+1. Merge `develop` into `main`
+2. Deploy the new contracts version to the testnets
+3. Update the `active_contracts.json` file on `main`
+4. Create a **draft** prerelease (e.g. `1.3.0-rc0`) on GitHub
+5. Wait for the managing DAO to approve on the testnets
+6. Update the NPM package version
+   - Create a PR to `main` with the release labels
+7. Unmark the Release as a draft and deploy the NPM packages
+
+**Fixes during Testing**
+
+1. Branch out from `main`
+2. Fix in in merged out branch
+3. Merge back into `main`
+4. Merge `main` back to `develop`
+5. Follow the `Testnets` release steps with `rc0` increment (e.g rc0 → rc1 or rc1 → rc2)
+
+**Mainnets**
+
+1. Deploy the new contracts version to both mainnets and testnets
+2. Update the `active_contracts.json` file on `main`
+3. Create a **draft** release (e.g. `1.3.0`) on GitHub
+4. Wait for the managing DAO to approve on mainnets and testnets
+5. Update the NPM package version (see [Releasing NPM packages](#releasing-npm-packages))
+   - Create a PR to `main` with the release labels
+6. Unmark the Release as a draft and deploy the NPM packages
+
+## Releasing NPM packages
 
 To release a new version of the NPM packages and the contracts add one of these labels `release:patch`, `release:minor` and `release:major`.
 This triggers the deployment of the contracts to the networks defined under `packages/contracts/networks.json`. Merges to `develop` triggers a release to testnets and merges to `main` releases to the mainnets.

UPDATE_CHECKLIST.md

@@ -4,20 +4,30 @@ This checklist is seen as a guide to update the existing deployment.
 
 ## Pre-Update
 
+- [ ] Verify that all changes of this update are reflected in [contracts/CHANGELOG.md](packages/contracts/CHANGELOG.md) by comparing the diff with the previous release commit.
+- [ ] Check that all contracts that undergo an upgrade and
+  - [ ] require reinitialzation are reinitialized correctly by an `upgradeToAndCall` call to a respective method with an incremented `renitializer(X)` number
+  - [ ] have new storage added to them
+    - [ ] decrement the storage gap correctly
+    - [ ] do not corrupt pre-existing storage
+    - [ ] initialize the storage correctly
 - [ ] Make sure that the `deploy` property in `packages/contracts/networks.json` points to the correct update
 - [ ] Run `yarn` in the repository root to install the dependencies
 - [ ] Run `yarn build` in `packages/contracts` to make sure the contracts compile
 - [ ] Run `yarn test` in `packages/contracts` to make sure the contract tests succeed
 - [ ] Set `ETH_KEY` in `.env` to the deployers private key. It doesn't have to be the previous deployer
 - [ ] Set the right API key for the chains blockchain explorer in `.env` (e.g. for mainnet it is `ETHERSCAN_KEY`)
 - [ ] Copy the managing DAO multisig env variables from `packages/subgraph/.env-example` into `packages/subgraph/.env`
+- [ ] Follow the version specific tasks in the section `Version tasks` 
 
 ## Update
 
 To update run `yarn deploy --network NETWORK` in `packages/contracts` and replace `NETWORK` with the correct network name (e.g. for mainnet it is `yarn deploy --network mainnet`).
 
 ## After-Update
 
+- [ ] Follow the version specific tasks in the section `Version tasks` 
+
 ### Configuration updates
 
 - [ ] Take the addresses from this file `packages/contracts/deployed_contracts.json`
@@ -80,3 +90,23 @@ if the new contracts **aren't** published:
 - [ ] Run `yarn deploy` in `packages/subgraph` to deploy the subgraph
 - [ ] Test the new deployed subgraph with the frontend team
 - [ ] Promote the new subgraph to live in the [Satsuma Dashboard](https://app.satsuma.xyz/dashboard)
+
+## Version tasks
+
+### v1.3.0
+
+#### Pre-Update
+
+Nothing to do.
+
+#### After-Update
+
+Wait until the managing DAO has made the necessary changes and then:
+
+- [ ] Verify that the managingDAO implementation has been updated
+- [ ] Verify that the managingDAO is reinitialized to `_initialized = 2`
+- [ ] Verify that the old DAOFactory has no permissions on the DAORegistry
+- [ ] Verify that the new DAOFactory has the `REGISTER_DAO_PERMISSION_ID` permission on the DAORegistry
+- [ ] Verify that Release 1 Build 2 of the multisig plugin has been created
+- [ ] Verify that Release 1 Build 2 of the token voting plugin has been created
+- [ ] Verify that Release 1 Build 2 of the addresslist voting plugin has been created