diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c1d60e60..a2d49fd30 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,19 +1,16 @@ Contributing to OpenZeppelin ======= -We really appreciate and value contributions to OpenZeppelin. Please take 5' to review the items listed below to make sure that your contributions are merged as soon as possible. +We really appreciate and value contributions to OpenZeppelin. Please take 5' to review the items listed below to make sure that your contributions are merged as soon as possible. ## Contribution guidelines -Smart contracts manage value and are highly vulnerable to errors and attacks. We have very strict guidelines, please make sure to review them: ["Contribution guidelines wiki entry"](https://github.com/OpenZeppelin/openzeppelin-solidity/wiki/Contribution-guidelines). +Smart contracts manage value and are highly vulnerable to errors and attacks. We have very strict [guidelines], please make sure to review them! ## Creating Pull Requests (PRs) As a contributor, you are expected to fork this repository, work on your own fork and then submit pull requests. The pull requests will be reviewed and eventually merged into the main repo. See ["Fork-a-Repo"](https://help.github.com/articles/fork-a-repo/) for how this works. -*IMPORTANT* -* Please see ["Git flow wiki entry"](https://github.com/OpenZeppelin/openzeppelin-solidity/wiki/Git-flow) for understanding how to use branches in this repository. - ## A typical workflow 1) Make sure your fork is up to date with the main repository: @@ -40,9 +37,9 @@ git commit "Fix some bug #123" git push origin fix/some-bug-#123 ``` -4) Go to [github.com/OpenZeppelin/openzeppelin-solidity](https://github.com/OpenZeppelin/zeppelin-solidity) in your web browser and issue a new pull request. +4) Go to [github.com/OpenZeppelin/openzeppelin-solidity](https://github.com/OpenZeppelin/openzeppelin-solidity) in your web browser and issue a new pull request. -*IMPORTANT* Read the PR template very carefully and make sure to follow all the instructions. These instructions +*IMPORTANT* Read the PR template very carefully and make sure to follow all the instructions. These instructions refer to some very important conditions that your PR must meet in order to be accepted, such as making sure that all tests pass, JS linting tests pass, solidity linting tests pass, etc. 5) Maintainers will review your code and possibly ask for changes before your code is pulled in to the main repository. We'll check that all tests pass, review the coding style, and check for general code correctness. If everything is OK, we'll merge your pull request and your code will be part of OpenZeppelin. @@ -56,3 +53,5 @@ If you have any questions feel free to post them to github.com/OpenZeppelin/open Finally, if you're looking to collaborate and want to find easy tasks to start, look at the issues we marked as ["Good first issue"](https://github.com/OpenZeppelin/openzeppelin-solidity/labels/good%20first%20issue). Thanks for your time and code! + +[guidelines]: GUIDELINES.md diff --git a/GUIDELINES.md b/GUIDELINES.md new file mode 100644 index 000000000..c88559517 --- /dev/null +++ b/GUIDELINES.md @@ -0,0 +1,64 @@ +Design Guidelines +======= + +These are some global design goals in OpenZeppelin. + +#### D0 - Security in Depth +We strive to provide secure, tested, audited code. To achieve this, we need to match intention with function. Thus, documentation, code clarity, community review and security discussions are fundamental. + +#### D1 - Simple and Modular +Simpler code means easier audits, and better understanding of what each component does. We look for small files, small contracts, and small functions. If you can separate a contract into two independent functionalities you should probably do it. + +#### D2 - Naming Matters + +We take our time with picking names. Code is going to be written once, and read hundreds of times. Renaming for clarity is encouraged. + +#### D3 - Tests + +Write tests for all your code. We encourage Test Driven Development so we know when our code is right. Even though not all code in the repository is tested at the moment, we aim to test every line of code in the future. + +#### D4 - Check preconditions and post-conditions + +A very important way to prevent vulnerabilities is to catch a contract’s inconsistent state as early as possible. This is why we want functions to check pre- and post-conditions for executing its logic. When writing code, ask yourself what you are expecting to be true before and after the function runs, and express it in code. + +#### D5 - Code Consistency + +Consistency on the way classes are used is paramount to an easier understanding of the library. The codebase should be as unified as possible. Read existing code and get inspired before you write your own. Follow the style guidelines. Don’t hesitate to ask for help on how to best write a specific piece of code. + +#### D6 - Regular Audits +Following good programming practices is a way to reduce the risk of vulnerabilities, but professional code audits are still needed. We will perform regular code audits on major releases, and hire security professionals to provide independent review. + +## Style Guidelines + +The design guidelines have quite a high abstraction level. These style guidelines are more concrete and easier to apply, and also more opinionated. + +### General + +#### G0 - Default to Solidity's official style guide. + +Follow the official Solidity style guide: https://solidity.readthedocs.io/en/latest/style-guide.html + +#### G1 - No Magic Constants + +Avoid constants in the code as much as possible. Magic strings are also magic constants. + +#### G2 - Code that Fails Early + +We ask our code to fail as soon as possible when an unexpected input was provided or unexpected state was found. + +#### G3 - Internal Amounts Must be Signed Integers and Represent the Smallest Units. + +Avoid representation errors by always dealing with weis when handling ether. GUIs can convert to more human-friendly representations. Use Signed Integers (int) to prevent underflow problems. + + +### Testing + +#### T1 - Tests Must be Written Elegantly + +Style guidelines are not relaxed for tests. Tests are a good way to show how to use the library, and maintaining them is extremely necessary. + +Don't write long tests, write helper functions to make them be as short and concise as possible (they should take just a few lines each), and use good variable names. + +#### T2 - Tests Must not be Random + +Inputs for tests should not be generated randomly. Accounts used to create test contracts are an exception, those can be random. Also, the type and structure of outputs should be checked. diff --git a/contracts/ARCHITECTURE.md b/contracts/ARCHITECTURE.md deleted file mode 100644 index bfb6cff8d..000000000 --- a/contracts/ARCHITECTURE.md +++ /dev/null @@ -1,27 +0,0 @@ -## Architecture - -The following provides visibility into how OpenZeppelin's contracts are organized: - -- **access** - Smart contracts that enable functionality that can be used for selective restrictions and basic authorization control functions. -- **crowdsale** - A collection of smart contracts used to manage token crowdsales that allow investors to purchase tokens with ETH. Includes a base contract which implements fundamental crowdsale functionality in its simplest form. The base contract can be extended in order to satisfy your crowdsale’s specific requirements. - - **distribution** - Includes extensions of the base crowdsale contract which can be used to customize the completion of a crowdsale. - - **emission** - Includes extensions of the base crowdsale contract which can be used to mint and manage how tokens are issued to purchasers. - - **price** - Includes extensions of the crowdsale contract that can be used to manage changes in token prices. - - **validation** - Includes extensions of the crowdsale contract that can be used to enforce restraints and limit access to token purchases. -- **examples** - A collection of simple smart contracts that demonstrate how to add new features to base contracts through multiple inheritance. -- **introspection** - An interface that can be used to make a contract comply with the ERC-165 standard as well as a contract that implements ERC-165 using a lookup table. -- **lifecycle** - A collection of base contracts used to manage the existence and behavior of your contracts and their funds. -- **math** - Libraries with safety checks on operations that throw on errors. -- **mocks** - A collection of abstract contracts that are primarily used for unit testing. They also serve as good usage examples and demonstrate how to combine contracts with inheritance when developing your own custom applications. -- **ownership** - A collection of smart contracts that can be used to manage contract and token ownership -- **payment** - A collection of smart contracts that can be used to manage payments through escrow arrangements, withdrawals, and claims. Includes support for both single payees and multiple payees. -- **proposals** - A collection of smart contracts that reflect community Ethereum Improvement Proposals (EIPs). These contracts are under development and standardization. They are not recommended for production, but they are useful for experimentation with pending EIP standards. Go [here](https://github.com/OpenZeppelin/openzeppelin-solidity/wiki/ERC-Process) for more information. - -- **token** - A collection of approved ERC standard tokens -- their interfaces and implementations. - - **ERC20** - A standard interface for fungible tokens: - - *Interfaces* - Includes the ERC-20 token standard basic interface. I.e., what the contract’s ABI can represent. - - *Implementations* - Includes ERC-20 token implementations that include all required and some optional ERC-20 functionality. - - **ERC721** - A standard interface for non-fungible tokens - - *Interfaces* - Includes the ERC-721 token standard basic interface. I.e., what the contract’s ABI can represent. - - *Implementations* - Includes ERC-721 token implementations that include all required and some optional ERC-721 functionality. -