docs: added and improved READMEs

README.md

@@ -1,6 +1,71 @@
 # osx-commons
 
-OSX-Commons: A collection of shared resources and utilities for the Aragon OSX DAO Framework, including subgraph, contract, and SDK functionalities.
+OSX-Commons: A collection of shared resources and utilities for the Aragon OSX DAO Framework, including contracts, subgraph, and SDK functionalities.
+
+## Project
+
+The root folder of the repo includes four subfolders:
+
+```markdown
+.
+├── configs
+├── contracts
+├── sdk
+├── subgraph
+├── ...
+└── package.json
+```
+
+- The `configs` folder contains general configurations such as the contract addresses for each network that Aragon OSx
+  has been officially deployed to, which are importable in JS/TS code.
+- The `contracts` folder contains Solidity smart contracts being used by the OSx framework and for plugin development.
+- The `sdk` folder contains various JS/TS helper functions that can be used in the OSx repo and plugin repos for
+  for testing and deployment.
+- The `subgraph` contains various JS/TS helper functions that can be used in the OSx repo and plugin repos for
+  for subgraph development.
+
+The root-level `package.json` file contains global `dev-dependencies` for formatting and linting. After installing the dependencies with
+
+```sh
+yarn install
+```
+
+you can run the associated [formatting](#formatting) and [linting](#linting) commands.
+
+### Formatting
+
+```sh
+yarn prettier:check
+```
+
+all `.sol`, `.js`, `.ts`, `.json`, and `.yml` files will be format-checked according to the specifications in `.prettierrc` file. With
+
+```sh
+yarn prettier:write
+```
+
+the formatting is applied.
+
+### Linting
+
+With
+
+```sh
+yarn lint
+```
+
+`.sol`, `.js`, and `.ts` files in the subfolders are analyzed with `solhint` and `eslint`, respectively.
+
+### Setting Environment Variables
+
+To be able to work on the contracts, make sure that you have created an `.env` file from the `.env.example` file and put in the API keys for
+
+- [Alchemy](https://www.alchemy.com) that we use as the web3 provider
+- [Alchemy Subgraphs](https://www.alchemy.com/subgraphs) that we use as the subgraph provider
+- the block explorer that you want to use depending on the networks that you want to deploy to
+
+You can also change the default hardhat private key (`PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"`).
+Note however, that the contracts in this repo are not meant to be deployed directly.
 
 ## Audits
 

contracts/README.md

@@ -0,0 +1,123 @@
+# Aragon OSx Commons Contracts
+
+This package contains the Solidity smart contracts to be used by the OSx framework and for plugin development.
+For audit information, refer to the ['Audits' section in the root level README.md](../README.md#audits).
+
+## Project
+
+The `contracts` folder includes the following Solidity contracts and libraries:
+
+```
+.
+├── dao
+│   └── IDAO.sol
+├── permission
+│   ├── PermissionLib.sol
+│   ├── auth
+│   │   ├── DaoAuthorizable.sol
+│   │   ├── DaoAuthorizableUpgradeable.sol
+│   │   └── auth.sol
+│   └── condition
+│       ├── IPermissionCondition.sol
+│       ├── PermissionCondition.sol
+│       └── PermissionConditionUpgradeable.sol
+├── plugin
+│   ├── IPlugin.sol
+│   ├── Plugin.sol
+│   ├── PluginCloneable.sol
+│   ├── PluginUUPSUpgradeable.sol
+│   ├── extensions
+│   │   ├── governance
+│   │   │   └── Addresslist.sol
+│   │   ├── membership
+│   │   │   └── IMembership.sol
+│   │   └── proposal
+│   │       ├── IProposal.sol
+│   │       ├── Proposal.sol
+│   │       └── ProposalUpgradeable.sol
+│   └── setup
+│       ├── IPluginSetup.sol
+│       ├── PluginSetup.sol
+│       └── PluginUpgradeableSetup.sol
+└── utils
+    ├── deployment
+    │   ├── ProxyFactory.sol
+    │   └── ProxyLib.sol
+    ├── math
+    │   ├── BitMap.sol
+    │   ├── Ratio.sol
+    │   └── UncheckedMath.sol
+    └── versioning
+        ├── IProtocolVersion.sol
+        ├── ProtocolVersion.sol
+        └── VersionComparisonLib.sol
+```
+
+In `contracts`, first run
+
+```sh
+yarn install
+```
+
+### Building
+
+First build the contracts with
+
+```sh
+yarn build
+```
+
+This will also generate the typechain bindings. During development of your smart contracts, changes can result
+in altered typechain bindings. You can remove the outdated build- and typechain-related files with
+
+```sh
+yarn clean
+```
+
+which will execute `yarn typechain` again. For convenience, use `yarn clean && yarn build`.
+
+### Testing
+
+To test your contracts, run
+
+```sh
+yarn test
+```
+
+### Linting
+
+Lint the Solidity and TypeScript code all together with
+
+```sh
+yarn lint
+```
+
+or separately with
+
+```sh
+yarn lint:sol
+```
+
+and
+
+```sh
+yarn lint:ts
+```
+
+### Coverage
+
+Generate the code coverage report with
+
+```sh
+yarn coverage
+```
+
+### Gas Report
+
+See the gas usage per test and average gas per method call with
+
+```sh
+REPORT_GAS=true yarn test
+```
+
+you can permanently enable the gas reporting by putting the `REPORT_GAS=true` into the `.env` file.