Skip to content

Commit

Permalink
Merge branch 'master' into azavalla-feature/inheritable-contract
Browse files Browse the repository at this point in the history
  • Loading branch information
@eternauta1337
eternauta1337 authored Jan 18, 2018
2 parents a5ea0af + 3a9a2c8 commit c8c0f21
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 86 deletions.
122 changes: 36 additions & 86 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,109 +1,59 @@
Contributing to Zeppelin
Contributing to OpenZeppelin
=======

## Design Guidelines
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.

These are some global design goals in Zeppelin.
## Contribution guidelines

### 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.
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/zeppelin-solidity/wiki/Contrbuting-guidelines).

### 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.
## Creating Pull Requests (PRs)

### D2 - Naming Matters
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.

We take our time with picking names. Code is going to be written once, and read hundreds of times. Renaming for clarity is encouraged.
*IMPORTANT*
* Please use `rebase` instead of `merge` when updating your fork.
* Please see ["Git flow wiki entry"](https://github.com/OpenZeppelin/zeppelin-solidity/wiki/Git-flow) for understanding how to use branches in this repository.

### D3 - Tests
## A typical workflow

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.
1) Make sure your fork is up to date with the main repository:

### 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.


### Documentation

TODO

## Pull Request Workflow
```
cd zeppelin-solidity
git fetch upstream
git checkout development
git pull --rebase upstream development
```
NOTE: The directory `zeppelin-solidity` represents your fork's local copy.

Our workflow is based on GitHub's pull requests. We use feature branches, prepended with: `test`, `feature`, `fix`, `refactor`, or `remove` according to the change the branch introduces. Some examples for such branches are:
```sh
git checkout -b test/some-module
git checkout -b feature/some-new-stuff
git checkout -b fix/some-bug
git checkout -b remove/some-file
2) Branch out from `development` into `fix/some-bug-#123`:
(Postfixing #123 will associate your PR with the issue #123 and make everyone's life easier =D)
```
git checkout -b fix/some-bug-#123
```

If your branch is planned to fix an open issue, postfix your branch name with the issue number like `fix/some-bug-#123`.
3) Make your changes, add your files, commit and push to your fork.

We expect pull requests to be rebased to the master branch before merging:
```sh
git remote add zep git@github.com:OpenZeppelin/zeppelin-solidity.git
git pull --rebase zep master
```
git add SomeFile.js
git commit "Fix some bug #123"
git push origin fix/some-bug-#123
```

Note that we require rebasing your branch instead of merging it, for commit readability reasons.
4) Go to [github.com/OpenZeppelin/zeppelin-solidity](https://github.com/OpenZeppelin/zeppelin-solidity) in your web browser and issue a new pull request.

After that, you can push the changes to your fork, by doing:
```sh
git push origin your_branch_name
git push origin feature/some-new-stuff
git push origin fix/some-bug
```
*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.

Finally go to [github.com/OpenZeppelin/zeppelin-solidity](https://github.com/OpenZeppelin/zeppelin-solidity) in your web browser and issue a new pull request.
*IMPORTANT* Please pay attention to the maintainer's feedback, since its a necessary step to keep up with the standards OpenZeppelin attains to.

Main contributors 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 Zeppelin.
## All set!

If you have any questions feel free to post them to
[github.com/OpenZeppelin/zeppelin-solidity/issues](https://github.com/OpenZeppelin/zeppelin-solidity/issues).
If you have any questions feel free to post them to github.com/OpenZeppelin/zeppelin-solidity/issues.

Finally, if you're looking to collaborate and want to find easy tasks to start, [look at the issues we marked as easy](https://github.com/OpenZeppelin/zeppelin-solidity/labels/easy).
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/zeppelin-solidity/labels/good%20first%20issue).

Thanks for your time and code!
1 change: 1 addition & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ Interested in contributing to OpenZeppelin?
- Framework proposal and roadmap: https://medium.com/zeppelin-blog/zeppelin-framework-proposal-and-development-roadmap-fdfa9a3a32ab#.iain47pak
- Issue tracker: https://github.com/OpenZeppelin/zeppelin-solidity/issues
- Contribution guidelines: https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/CONTRIBUTING.md
- Wiki: https://github.com/OpenZeppelin/zeppelin-solidity/wiki

## Collaborating organizations and audits by OpenZeppelin
- [Golem](https://golem.network/)
Expand Down

0 comments on commit c8c0f21

Please sign in to comment.