Added more comprehensive usage information to the Getting Started guide #1089

dougiebuckets · 2018-07-18T18:59:29Z

Added an Architecture section that speaks to the different types of contracts
Added a Tests section that provides high-level visibility into what is used for unit testing
Added a How To Use and Modify OpenZeppelin Contracts section
Added development principles to the existing Security section

🚀 Description

📘 I've reviewed the OpenZeppelin Contributor Guidelines
📖 I've made sure that my contracts are well-documented.
🎨 I've run the JS/Solidity linters and fixed any issues (npm run lint:all:fix).

nventuro · 2018-07-18T20:28:57Z

README.md

+## 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. Includes address whitelisting and signature-based permissions management.


From this description, it's clear to me that this is where RBAC belongs, @shrugs WDYT?

Even the 'a' stands for 'access'.

yeah agreed. I think Ownable should go in here as well, but I doubt we want to move that :D

added an issue: #1093

nventuro · 2018-07-18T20:36:22Z

README.md

+	- *Implementations* - Includes ERC-721 token implementations that include all required and some optional ERC-721 functionality.
+
+## Tests
+Unit test are critical to the OpenZeppelin framework. They help ensure code quality and mitigate against security vulnerabilities. The directory structure within the `/tests` directory corresponds to the `/contracts` directory. OpenZeppelin uses Mocha’s JavaScript testing framework and Chai’s assertion library. To learn more about how to tests are structured, please reference OpenZeppelin’s Testing Guide.


Do we already have a Testing Guide that I'm unaware of, or is this referencing #1077?

@nventuro Good question. Yup, this is referencing #1077.

nventuro · 2018-07-18T20:39:09Z

README.md

 ## Security
 OpenZeppelin is meant to provide secure, tested and community-audited code, but please use common sense when doing anything that deals with real money! We take no responsibility for your implementation decisions and any security problem you might experience.

+The core development principles and strategies that OpenZeppelin is based on include: security in depth, simple and modular code, clarity-driven naming conventions, comprehensive unit testing, pre-and-post-condition sanity checks, code consistency, and regular audits.


Maybe add a link to the wiki? https://github.com/OpenZeppelin/openzeppelin-solidity/wiki/Contribution-guidelines

The wiki will be deprecated eventually though, so I'm not sure how to proceed here.

nventuro · 2018-07-18T20:42:19Z

This looks great, thanks! 🎉

I think some of the directory descriptions may be a bit too specific, detailing what's currently there, instead of the spirit of that location. E.g.: **math** - Libraries with safety checks used to prevent against overflows and underflows., or introspection directly referencing ERC-165. @frangio thoughts?

shrugs · 2018-07-18T23:02:30Z

README.md

+- **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 used to prevent against overflows and underflows.
+- **mocks** - A collection of abstract contracts that can be used as the foundation for your own custom implementations. The mock contracts demonstrate how OpenZeppelin’s secure base contracts can be used with multiple inheritance.


let's mention that the mocks are used primarily for tests, but also serve as good examples for usage and combinations

shrugs · 2018-07-18T23:03:21Z

README.md

+- **math** - Libraries with safety checks used to prevent against overflows and underflows.
+- **mocks** - A collection of abstract contracts that can be used as the foundation for your own custom implementations. The mock contracts demonstrate how OpenZeppelin’s secure base contracts can be used with multiple inheritance.
+- **ownership** - A collection of smart contracts that can be used to manage contract and token ownership
+	- **rbac** - A library used to manage addresses assigned to different user roles and an example RBAC interface that demonstrates how to handle setters and getters for roles and addresses.


let's add the full "Role Based Access Control" text instead of RBAC interface so people know what it stands for right away.

shrugs · 2018-07-18T23:05:50Z

README.md

+	- **rbac** - A library used to manage addresses assigned to different user roles and an example RBAC interface that demonstrates how to handle setters and getters for roles and addresses.
+
+- **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). The smart contracts here are under consideration for inclusion in OpenZeppelin. They are not recommended for use until the community has thoroughly evaluated and approved them.


let's add a link to https://github.com/OpenZeppelin/openzeppelin-solidity/wiki/ERC-Process so people can get the full details.

Maybe instead of "not recommended for use..." we can say something like "these contracts are under development and standardization, so they're not recommended for production contracts, but are useful for experimentation with pending EIP standards."

shrugs · 2018-07-18T23:06:17Z

README.md

+- **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). The smart contracts here are under consideration for inclusion in OpenZeppelin. They are not recommended for use until the community has thoroughly evaluated and approved them.
+- **token** - A collection of approved ERC standard tokens -- their interfaces and implementations.
+- **ERC20** - A standard interface for fungible tokens:


indenting on ERC20 and ERC721 needs to be under token I believe

shrugs · 2018-07-18T23:06:59Z

README.md

+Unit test are critical to the OpenZeppelin framework. They help ensure code quality and mitigate against security vulnerabilities. The directory structure within the `/tests` directory corresponds to the `/contracts` directory. OpenZeppelin uses Mocha’s JavaScript testing framework and Chai’s assertion library. To learn more about how to tests are structured, please reference OpenZeppelin’s Testing Guide.
+
+## How To Use And Modify OpenZeppelin Contracts
+When using OpenZeppelin to build your own distributed applications, for security reasons we encourage you NOT to modify the framework’s base contracts, libraries, and interfaces. In order to leverage and extend their functionality, we encourage you to inherit from them.


"inherit from them or compose them together with your own contracts."

shrugs · 2018-07-18T23:07:56Z

README.md

+## How To Use And Modify OpenZeppelin Contracts
+When using OpenZeppelin to build your own distributed applications, for security reasons we encourage you NOT to modify the framework’s base contracts, libraries, and interfaces. In order to leverage and extend their functionality, we encourage you to inherit from them.
+
+The Solidity programming language supports multiple inheritance. This is very powerful yet it can also be confusing. The more complexity you introduce to your distributed applications through multiple inheritance, the greater your application’s attack surface is.


nit: can we add a : in between these two sentences, like: This is very powerful, but can also be confusing: the more complexity you introduce to your distributed applications...

shrugs · 2018-07-18T23:08:08Z

README.md

+
+The Solidity programming language supports multiple inheritance. This is very powerful yet it can also be confusing. The more complexity you introduce to your distributed applications through multiple inheritance, the greater your application’s attack surface is.
+
+You’ll notice in the `/mocks` directory there are a collection of abstract contracts that can be used as the foundation for your own custom implementations. These mock contracts demonstrate how OpenZeppelin’s secure base contracts can be used with multiple inheritance.


likewise for testing purposes here

dougiebuckets · 2018-07-19T11:38:48Z

@shrugs @nventuro - Thanks for the feedback! Updates made :)

nventuro · 2018-07-27T02:49:34Z

README.md

+- **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 inheritence when developing your own custom applciations.
+- **ownership** - A collection of smart contracts that can be used to manage contract and token ownership
+	- **rbac** - A library used to manage addresses assigned to different user roles and an example Role-Based Access Control (RBAC) interface that demonstrates how to handle setters and getters for roles and addresses.


As of #1114 (thanks to you!), RBAC is now under access :)

Awesome! Update made to docs. Thanks for your help.

nventuro · 2018-07-27T02:52:37Z

README.md

+
+The Solidity programming language supports multiple inheritance. This is very powerful yet it can also be confusing: the more complexity you introduce to your distributed applications through multiple inheritance, the greater your application’s attack surface is.
+
+You’ll notice in the `/mocks` directory there are a collection of abstract contracts used for testing that can also be used as the foundation for your own custom implementations. These mock contracts demonstrate how OpenZeppelin’s secure base contracts can be used with multiple inheritance.


I'd mention once more that mocks are intended primarily for testing (though it's true that they may illustrate usage).

* Added an Architecture section that speaks to the different types of contracts * Added a Tests section that provides high-level visibility into what is used for unit testing * Added a How To Use and Modify OpenZeppelin Contracts section * Added development principles to the existing Security section

nventuro

Great, thanks @dougiebuckets! We might revamp the directories a bit before the 2.0 release, this is a great starting point for the upcoming readme :)

nventuro reviewed Jul 18, 2018

View reviewed changes

shrugs reviewed Jul 18, 2018

View reviewed changes

dougiebuckets force-pushed the more-detail-in-getting-started-guide-#1081 branch from 0005687 to fcb663f Compare July 19, 2018 11:11

nventuro added kind:improvement documentation Inline comments, guides, and examples. labels Jul 21, 2018

nventuro reviewed Jul 27, 2018

View reviewed changes

dougiebuckets force-pushed the more-detail-in-getting-started-guide-#1081 branch from fcb663f to 4c4fd7f Compare July 27, 2018 12:11

nventuro approved these changes Jul 27, 2018

View reviewed changes

nventuro merged commit f5b0bb3 into OpenZeppelin:master Jul 27, 2018


		The Solidity programming language supports multiple inheritance. This is very powerful yet it can also be confusing. The more complexity you introduce to your distributed applications through multiple inheritance, the greater your application’s attack surface is.

		You’ll notice in the `/mocks` directory there are a collection of abstract contracts that can be used as the foundation for your own custom implementations. These mock contracts demonstrate how OpenZeppelin’s secure base contracts can be used with multiple inheritance.

Added more comprehensive usage information to the Getting Started guide #1089

Added more comprehensive usage information to the Getting Started guide #1089

Uh oh!

Conversation

dougiebuckets commented Jul 18, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Description

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nventuro commented Jul 18, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dougiebuckets commented Jul 19, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dougiebuckets Jul 27, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nventuro left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dougiebuckets commented Jul 18, 2018 •

edited

Loading

dougiebuckets Jul 27, 2018 •

edited

Loading