Merge branch 'staging' into feat/add-PSP-docs

aragon · Jun 6, 2024 · 46a0c3b · 46a0c3b
2 parents 01d1124 + 20dfc62
commit 46a0c3b
Show file tree

Hide file tree

Showing 31 changed files with 265 additions and 806 deletions.
diff --git a/docs/advanced/technical-reference/_category_.yml b/docs/advanced/technical-reference/_category_.yml
@@ -1,5 +1,3 @@
 collapsible: true
 collapsed: true
-label: Technical Reference
-link: null
 position: 6
diff --git a/docs/advanced/technical-reference/index.md b/docs/advanced/technical-reference/index.md
@@ -1,6 +1,6 @@
 ---
-title: Technical - Reference
-sidebar_label: Technical - Reference
+title: Technical Reference
+sidebar_label: Technical Reference
 ---
 
 ## Reference Guide

diff --git a/docs/overview/overview/index.md b/docs/overview/overview/index.md
@@ -1,4 +1,5 @@
 ---
+slug: /
 title: What is Aragon OSx?
 sidebar_label: Introduction
 sidebar_position: 0

diff --git a/docs/support/FAQ.md b/docs/support/FAQ.md
@@ -0,0 +1,21 @@
+---
+title: FAQ
+sidebar_label: FAQ
+sidebar_position: 3
+---
+
+##
+
+Aragon FAQ
+
+### DAO ???
+
+This section will contain docs.
+
+### Plugin ???
+
+This section will contain docs.
+
+### Proposal ???
+
+This section will contain docs.
diff --git a/docs/support/_category_.yml b/docs/support/_category_.yml
diff --git a/docs/support/dos-donts/_category_.yml → docs/support/best-practices/_category_.yml b/docs/support/dos-donts/_category_.yml → docs/support/best-practices/_category_.yml
@@ -1,4 +1,4 @@
 collapsible: false
 collapsed: false
-label: DO's vs DONT'S
+label: Best Practices
 position: 1
diff --git a/docs/support/best-practices/developing-plugin.md b/docs/support/best-practices/developing-plugin.md
@@ -0,0 +1,32 @@
+---
+title: Developing a Plugin
+sidebar_label: Developing a Plugin
+sidebar_position: 0
+---
+
+## Advice for Developing a Plugin
+
+### DOs 👌
+
+- Document your contracts using [NatSpec](https://docs.soliditylang.org/en/v0.8.17/natspec-format.html).
+- Test your contracts, e.g., using toolkits such as [hardhat (JS)](https://hardhat.org/hardhat-runner/docs/guides/test-contracts) or [Foundry (Rust)](https://book.getfoundry.sh/forge/tests).
+- Use the `auth` modifier to control the access to functions in your plugin instead of `onlyOwner` or similar.
+- Write plugins implementations that need minimal permissions on the DAO.
+- Write `PluginSetup` contracts that remove all permissions on uninstallation that they requested during installation or updates.
+- Plan the lifecycle of your plugin (need for upgrades).
+- Follow our [versioning guidelines](../02-plugin-development/07-publication/01-versioning.md).
+
+### DON'Ts ✋
+
+- Leave any contract uninitialized.
+- Grant the `ROOT_PERMISSION_ID` permission to anything or anyone.
+- Grant with `who: ANY_ADDR` unless you know what you are doing.
+- Expect people to grant or revoke any permissions manually during the lifecycle of a plugin. The `PluginSetup` should take this complexity away from the user and after uninstallation, all permissions should be removed.
+- Write upgradeable contracts that:
+  - Repurpose existing storage (in upgradeable plugins).
+  - Inherit from previous versions as this can mess up the inheritance chain. Instead, write self-contained contracts.
+
+<!-- - A plugin requesting the exact same permission to another one + uninstalling it -->
+<!-- - Publishing plugin versions that provide no guarantees (setup contracts upgradeable behind the scenes by the dev)-->
+
+In the following sections, you will learn about the details about plugin development.
diff --git a/docs/support/best-practices/operating-dao.md b/docs/support/best-practices/operating-dao.md
@@ -0,0 +1,24 @@
+---
+title: Operating a DAO
+sidebar_label: Operating a DAO
+sidebar_position: 0
+---
+
+## Some Advice When Operating your DAO
+
+### DOs 👌
+
+- Make sure that at least one address (typically a governance plugin) has `EXECUTE_PERMISSION_ID` permission so that something can be executed on behalf of the DAO.
+- Check every proposal asking to install, update, or uninstall a plugin with utmost care and review. Installation means granting an external contract permissions to do things on behalf of your DAO, so you want to be extra careful about:
+  - the implementation contract
+  - the setup contract
+  - the helper contracts
+  - the permissions being granted/revoked
+
+### DON'Ts ✋
+
+- Incapacitate your DAO by revoking all `EXECUTE_PERMISSION`. This means your DAO will be blocked and any assets you hold may be locked in forever. This can happen through:
+  - uninstalling your last governance plugin.
+  - applying an update to your last governance plugin.
+- Don't give permissions to directly call functions from the DAO. Better and safer to use a plugin instead.
+- If you're using the Token Voting plugin in your DAO, make sure you don't mint additional tokens without careful consideration. If you mint too many at once, this may lock your DAO, since you will not be able to reach the minimum participation threshold. This happens if there are not enough tokens already on the market to meet the minimum participation percentage and the DAO owns most of the governance tokens.
diff --git a/docs/support/dos-donts/index.md b/docs/support/dos-donts/index.md
diff --git a/docs/support/faq/_category_.yml b/docs/support/faq/_category_.yml
diff --git a/docs/support/faq/index.md b/docs/support/faq/index.md
diff --git a/docs/support/glossary.md b/docs/support/glossary.md
@@ -0,0 +1,21 @@
+---
+title: Glossary
+sidebar_label: Glossary
+sidebar_position: 2
+---
+
+##
+
+Aragon Glossary
+
+### DAO
+
+This section will contain docs.
+
+### Plugin
+
+This section will contain docs.
+
+### Proposal
+
+This section will contain docs.
diff --git a/docs/support/glossary/_category_.yml b/docs/support/glossary/_category_.yml
diff --git a/docs/support/glossary/dao.md b/docs/support/glossary/dao.md
diff --git a/docs/support/glossary/plugin.md b/docs/support/glossary/plugin.md
diff --git a/docs/support/index.md b/docs/support/index.md
@@ -4,6 +4,6 @@ sidebar_label: Support
 sidebar_position: 0
 ---
 
-## Support
+## Overview
 
 This section will contain docs.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -13,10 +13,9 @@ const config = {
   tagline: "Let's build amazing things together",
   url: 'https://devs.aragon.org',
   baseUrl: '/',
-
-  onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'throw',
-  onBrokenAnchors: 'throw',
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+  onBrokenAnchors: 'warn',
 
   favicon: 'img/Aragon-logo-circle.png',
 
@@ -25,6 +24,7 @@ const config = {
       '@docusaurus/preset-classic',
       {
         docs: {
+          routeBasePath: '/',
           sidebarPath: require.resolve('./sidebars.js'),
           remarkPlugins: [math],
           rehypePlugins: [katex],
@@ -194,7 +194,7 @@ const config = {
         rootPath: './versioned_docs/version-1.3.0',
         baseURL: 'osx/subgraph/reference-guide',
         homepage: './static/subgraph/index.md',
-        linkRoot: '/docs/1.3.0',
+        linkRoot: '/1.3.0',
         loaders: {
           JsonFileLoader: {
             module: '@graphql-tools/json-file-loader',

diff --git a/src/components/ComponentCard/index.tsx b/src/components/ComponentCard/index.tsx
diff --git a/src/components/index.ts b/src/components/index.ts
@@ -1,4 +1,3 @@
-export * from './ComponentCard';
 export * from './Footer';
 export * from './HeroHeader';
 export * from './WelcomeCard';

diff --git a/src/data/ComponentCards.tsx b/src/data/ComponentCards.tsx
diff --git a/src/data/WelcomeCards.tsx b/src/data/WelcomeCards.tsx