From e4999cb5b2b7fe94e1112fdb569a63619006c865 Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 11:34:57 +0200 Subject: [PATCH 1/8] Add CONTRIBUTING.md --- CONTRIBUTING.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..0d1ab928d2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# Contributing to Aragon + +:tada: Thank you for being interested in contributing to Aragon! :tada: + +Feel welcome and read the following sections in order to know how to ask questions and how to work on something. + +There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into the project. + +All members of our community are expected to follow our [Code of Conduct](https://wiki.aragon.org/documentation/Code_of_Conduct/). Please make sure you are welcoming and friendly in all of our spaces. + +## Your first contribution + +Unsure where to begin contributing to Aragon? + +You can start with a [Good First Issue](https://github.com/aragon/aragon-apps/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). + +> Good first issues are usually for small features, additional tests, spelling / grammar fixes, formatting changes, or other clean up. + +Start small, pick a subject you care about, are familiar with, or want to learn. + +If you're not already familiar with git or Github, here are a couple of friendly tutorials: [First Contributions](https://github.com/firstcontributions/first-contributions), [Open Source Guide](https://opensource.guide/), and [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). + +## How to file an issue or report a bug + +If you see a problem, you can report it in our [issue tracker](https://github.com/aragon/aragon-apps/issues) (or the [Aragon client's](https://github.com/aragon/aragon/issues)). + +Please take a quick look to see if the issue doesn't already exist before filing yours. + +Do your best to include as many details as needed in order for someone else to fix the problem and resolve the issue. + +#### If you find a security vulnerability, do NOT open an issue. Email security@aragon.org instead. + +In order to determine whether you are dealing with a security issue, ask yourself these two questions: + +- Can I access or steal something that's not mine, or access something I shouldn't have access to? +- Can I disable something for other people? + +If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, please send a email. + +#### If you're interested in the smart contracts underlying Aragon, a [bug bounty program](https://wiki.aragon.org/dev/bug_bounty/) with payouts up to $50,000 is available for rewarding contributors who find security vulnerabilities. + +## Fixing issues + +1. [Find an issue](https://github.com/aragon/aragon-apps/issues) that you are interested in. + - You may want to ask on the issue or on Aragon Chat's [#dev channel](https://aragon.chat/channel/dev) if anyone has already started working on the issue. +1. Fork and clone a local copy of the repository. +1. Make the appropriate changes for the issue you are trying to address or the feature that you want to add. +1. Push the changes to the remote repository. +1. Submit a pull request in Github, explaining any changes and further questions you may have. +1. Wait for the pull request to be reviewed. +1. Make changes to the pull request if the maintainer recommends them. +1. Celebrate your success after your pull request is merged! + +It's OK if your pull request is not perfect (no pull request is). +The reviewer will be able to help you fix any problems and improve it! + +You can also edit a page directly through your browser by clicking the "EDIT" link in the top-right corner of any page and then clicking the pencil icon in the github copy of the page. + +## Styleguide and development processes + +For the frontends, we use [prettier](https://prettier.io/) and [eslint](https://eslint.org/) to automatically lint and format the project. +For the contracts, we use [eth-lint](https://github.com/duaraghav8/Ethlint) to automatically lint the project. + +We generally avoid adding external dependencies if they can be ported over easily, due to numerous NPM-related security issues in the past (e.g. [`event-stream`](https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident)). + +### Git branch convention + +Due to the unconventional release process of smart contracts, this repo utilizes a slightly different flow of git. + +The main problem is that smart contracts should be heavily scrutinized before a release, making the process cumbersome and unlike the release process for "normal" dependencies or apps. [See here](https://forum.aragon.org/t/git-branch-convention-for-aragon-repos/298/3) for a more detailed explanation. + +Thus, we use the following convention: + +- Any change that can be release immediately, base on `master` +- Any change that should be staged for longer review (e.g. contract functionality changes pending security review), base on `next` + +As `next` becomes ready, merge `next` onto `master` with a rebase. + +## Community + +If you need help, please reach out to Aragon core contributors and community members in the Aragon Chat [#dev](https://aragon.chat/channel/dev) and [#dev-help](https://aragon.chat/channel/dev-help) channels. We'd love to hear from you and know what you're working on! From 7d3cc6eba6e465f9b15043783f2724064490e4d8 Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 11:35:06 +0200 Subject: [PATCH 2/8] Improve README.md --- README.md | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 8d8d99d5cd..c4955612bc 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,19 @@ This repository contains the following apps: -- **[Vault](apps/vault)**: Securely owns and manages tokens on behalf of a DAO. - **[Finance](apps/finance)**: Send payments and manage expenses with budgeting. -- **[Voting](apps/voting)**: Create votes that execute actions on behalf of token holders. +- **[Survey](apps/survey)**: Create polls to gauge community opinions. - **[Tokens](apps/token-manager)**: Manages organization tokens. +- **[Vault](apps/vault)**: Securely owns and manages tokens on behalf of a DAO. +- **[Voting](apps/voting)**: Create votes that execute actions on behalf of token holders. + +Each of these apps come with a frontend that is compatible with the [Aragon client](http://github.com/aragon/aragon). You can read more about how the individual apps work in the [Aragon user guide](https://help.aragon.org/category/15-aragon-apps). ## Coming soon apps -The following apps are still under development, not ready for production deployment yet: +The following apps are still under development, and not ready for production deployment yet: - **[Payroll](future-apps/payroll)**: Manages employees' payrolls. @@ -23,15 +26,37 @@ The following apps are still under development, not ready for production deploym npm install ``` -This installs global package dependencies and also bootstraps lerna packages. +This installs global package dependencies and also bootstraps the entire monorepo through [`lerna`](https://github.com/lerna/lerna). + +> **Note**: the monorepo is set up in such a way that you **must** install it through a `lerna bootstrap` (done automatically after an `npm install`). +> If you're only interested in the contract dependencies, and not the frontends, you can use `INSTALL_FRONTEND=false npm install` instead. +> If you're only interested in bootstrapping one package, you can use `npx lerna bootstrap --scope @aragon/ --inclede-filtered-dependencies` + +Running tests on all apps can be done by running `npm run test` at the root directory (note that running all of the tests can take a significant amount of time!). + +Running tests of an individual app can be done by running `npm run test` inside an individual app's directory, or through the selective `npm run test:` scripts. + +By default, tests are run in a in-memory instance of testrpc. + +### Frontends + +Developing the frontends locally can be a bit tricky. + +For now, you can follow [@bpierre's gist](https://gist.github.com/bpierre/22572415b90577aa17e5953fa68980eb#developing-the-apps) on starting an app's local frontend server and connecting it to a locally running Aragon client. + +In the future, we will improve this flow to make it much easier to get started. + +## Contributing + +#### 👋 Get started contributing with a [good first issue](https://github.com/aragon/aragon-apps/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). -Running tests on all apps can be done running `npm run test` at the root directory. Running tests of an individual app can be done by running `npm run test` inside the app directory. +Don't be shy to contribute even the smallest tweak. 🐲 There are still some dragons to be aware of, but we'll be here to help you get started! -By default tests are run in a in-memory instance of testrpc. +For more details about contributing to Aragon, please check the [contributing guide](./CONTRIBUTING.md). -## Issues +#### Issues -If you come across an issue with Aragon Core, do a search in the [Issues](https://github.com/aragon/aragon-apps/issues?utf8=%E2%9C%93&q=is%3Aissue) tab of this repo and the [Aragon Core Issues](https://github.com/aragon/aragon/issues?utf8=%E2%9C%93&q=is%3Aissue) to make sure it hasn't been reported before. Follow these steps to help us prevent duplicate issues and unnecessary notifications going to the many people watching this repo: +If you come across an issue with Aragon, do a search in the [Issues](https://github.com/aragon/aragon/issues?utf8=%E2%9C%93&q=is%3Aissue) tab of this repo and the [Aragon Apps Issues](https://github.com/aragon/aragon-apps/issues?utf8=%E2%9C%93&q=is%3Aissue) to make sure it hasn't been reported before. Follow these steps to help us prevent duplicate issues and unnecessary notifications going to the many people watching this repo: - If the issue you found has been reported and is still open, and the details match your issue, give a "thumbs up" to the relevant posts in the issue thread to signal that you have the same issue. No further action is required on your part. - If the issue you found has been reported and is still open, but the issue is missing some details, you can add a comment to the issue thread describing the additional details. From 7821a020c121f354ede050e1c8cee96509e714ab Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 11:35:20 +0200 Subject: [PATCH 3/8] Fix install script not accepting INSTALL_FRONTEND override --- scripts/install | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/install b/scripts/install index d12339a9ac..2e027dada1 100755 --- a/scripts/install +++ b/scripts/install @@ -6,6 +6,7 @@ const inCI = 'TRAVIS' in process.env && 'CI' in process.env if (inCI) { execute('npm run bootstrap:ci', { stdio: 'inherit' }) } else { - process.env.INSTALL_FRONTEND = true + process.env.INSTALL_FRONTEND = + process.env.INSTALL_FRONTEND === undefined ? true : process.env.INSTALL_FRONTEND execute('npm run bootstrap -- --nohoist=@aragon/cli', { stdio: 'inherit' }) } From b1b5df0761fe41da557deedf166aa37ec88decb2 Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 12:28:47 +0200 Subject: [PATCH 4/8] Add links to master and next branches --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d1ab928d2..1f8e06f8ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,8 +71,8 @@ The main problem is that smart contracts should be heavily scrutinized before a Thus, we use the following convention: -- Any change that can be release immediately, base on `master` -- Any change that should be staged for longer review (e.g. contract functionality changes pending security review), base on `next` +- Any change that can be release immediately, base on [`master`](https://github.com/aragon/aragon-apps/tree/master) +- Any change that should be staged for longer review (e.g. contract functionality changes pending security review), base on [`next`](https://github.com/aragon/aragon-apps/tree/next) As `next` becomes ready, merge `next` onto `master` with a rebase. From 06c83eb8f758e33a1b8733261b37b47dd33a3dc1 Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 12:44:02 +0200 Subject: [PATCH 5/8] Small cosmetic changes --- CONTRIBUTING.md | 1 + README.md | 16 ++++++++++------ 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f8e06f8ec..2d64d6964c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,7 @@ You can also edit a page directly through your browser by clicking the "EDIT" li ## Styleguide and development processes For the frontends, we use [prettier](https://prettier.io/) and [eslint](https://eslint.org/) to automatically lint and format the project. + For the contracts, we use [eth-lint](https://github.com/duaraghav8/Ethlint) to automatically lint the project. We generally avoid adding external dependencies if they can be ported over easily, due to numerous NPM-related security issues in the past (e.g. [`event-stream`](https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident)). diff --git a/README.md b/README.md index c4955612bc..dfc6b36c7a 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ This repository contains the following apps: - **[Vault](apps/vault)**: Securely owns and manages tokens on behalf of a DAO. - **[Voting](apps/voting)**: Create votes that execute actions on behalf of token holders. -Each of these apps come with a frontend that is compatible with the [Aragon client](http://github.com/aragon/aragon). +Each of the individual apps come with a frontend that is intended to be installed and used through the [Aragon client](http://github.com/aragon/aragon). -You can read more about how the individual apps work in the [Aragon user guide](https://help.aragon.org/category/15-aragon-apps). +You can read more about how each of the individual apps work in the [Aragon user guide](https://help.aragon.org/category/15-aragon-apps). ## Coming soon apps @@ -29,8 +29,10 @@ npm install This installs global package dependencies and also bootstraps the entire monorepo through [`lerna`](https://github.com/lerna/lerna). > **Note**: the monorepo is set up in such a way that you **must** install it through a `lerna bootstrap` (done automatically after an `npm install`). +> > If you're only interested in the contract dependencies, and not the frontends, you can use `INSTALL_FRONTEND=false npm install` instead. -> If you're only interested in bootstrapping one package, you can use `npx lerna bootstrap --scope @aragon/ --inclede-filtered-dependencies` +> +> If you're only interested in bootstrapping one package, you can use `npx lerna bootstrap --scope @aragon/ --include-filtered-dependencies` Running tests on all apps can be done by running `npm run test` at the root directory (note that running all of the tests can take a significant amount of time!). @@ -38,16 +40,18 @@ Running tests of an individual app can be done by running `npm run test` inside By default, tests are run in a in-memory instance of testrpc. -### Frontends +### App frontends -Developing the frontends locally can be a bit tricky. +Developing the frontends locally can be a bit tricky, due to the frontends' reliance on a properly configured Aragon client. -For now, you can follow [@bpierre's gist](https://gist.github.com/bpierre/22572415b90577aa17e5953fa68980eb#developing-the-apps) on starting an app's local frontend server and connecting it to a locally running Aragon client. +For now, you can follow [@bpierre's gist](https://gist.github.com/bpierre/22572415b90577aa17e5953fa68980eb#developing-the-apps) to start an app's local frontend server and connect it to a locally running Aragon client. In the future, we will improve this flow to make it much easier to get started. ## Contributing +For some introductory information on what an Aragon app is, and how to build one, please read through the [architecture introduction](https://hack.aragon.org/docs/stack) and [Your first Aragon app](https://hack.aragon.org/docs/tutorial). The [aragonAPI documentation](https://hack.aragon.org/docs/api-intro) is also available as a reference. + #### 👋 Get started contributing with a [good first issue](https://github.com/aragon/aragon-apps/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). Don't be shy to contribute even the smallest tweak. 🐲 There are still some dragons to be aware of, but we'll be here to help you get started! From 499d93c72b49f051dba65afce27644bad97b6612 Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 16:33:30 +0200 Subject: [PATCH 6/8] Move developing guide to CONTRIBUTING --- CONTRIBUTING.md | 16 +++++++++++++++- README.md | 12 ++---------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d64d6964c..868f0bd433 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,12 +56,26 @@ The reviewer will be able to help you fix any problems and improve it! You can also edit a page directly through your browser by clicking the "EDIT" link in the top-right corner of any page and then clicking the pencil icon in the github copy of the page. -## Styleguide and development processes +### Tips and Tricks + +Windows users may need to install the [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) before installing this project's dependencies. + +#### App frontends + +Developing the frontends locally can be a bit tricky, due to the frontends' reliance on a properly configured Aragon client. + +For now, you can follow [`@bpierre's` gist](https://gist.github.com/bpierre/22572415b90577aa17e5953fa68980eb#developing-the-apps) to start an app's local frontend server and connect it to a locally running Aragon client. + +In the future, we will improve this flow to make it much easier to get started. + +### Styleguide and development processes For the frontends, we use [prettier](https://prettier.io/) and [eslint](https://eslint.org/) to automatically lint and format the project. For the contracts, we use [eth-lint](https://github.com/duaraghav8/Ethlint) to automatically lint the project. +Handy npm scripts (usually `npm run lint`) are provided at all levels to help automate these checks. + We generally avoid adding external dependencies if they can be ported over easily, due to numerous NPM-related security issues in the past (e.g. [`event-stream`](https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident)). ### Git branch convention diff --git a/README.md b/README.md index dfc6b36c7a..5e1ec21028 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ The following apps are still under development, and not ready for production dep - **[Payroll](future-apps/payroll)**: Manages employees' payrolls. -## Developing +## Quick start ``` npm install @@ -40,14 +40,6 @@ Running tests of an individual app can be done by running `npm run test` inside By default, tests are run in a in-memory instance of testrpc. -### App frontends - -Developing the frontends locally can be a bit tricky, due to the frontends' reliance on a properly configured Aragon client. - -For now, you can follow [@bpierre's gist](https://gist.github.com/bpierre/22572415b90577aa17e5953fa68980eb#developing-the-apps) to start an app's local frontend server and connect it to a locally running Aragon client. - -In the future, we will improve this flow to make it much easier to get started. - ## Contributing For some introductory information on what an Aragon app is, and how to build one, please read through the [architecture introduction](https://hack.aragon.org/docs/stack) and [Your first Aragon app](https://hack.aragon.org/docs/tutorial). The [aragonAPI documentation](https://hack.aragon.org/docs/api-intro) is also available as a reference. @@ -60,7 +52,7 @@ For more details about contributing to Aragon, please check the [contributing gu #### Issues -If you come across an issue with Aragon, do a search in the [Issues](https://github.com/aragon/aragon/issues?utf8=%E2%9C%93&q=is%3Aissue) tab of this repo and the [Aragon Apps Issues](https://github.com/aragon/aragon-apps/issues?utf8=%E2%9C%93&q=is%3Aissue) to make sure it hasn't been reported before. Follow these steps to help us prevent duplicate issues and unnecessary notifications going to the many people watching this repo: +If you come across an issue with Aragon, do a search in the [Issues](https://github.com/aragon/aragon-apps/issues?utf8=%E2%9C%93&q=is%3Aissue) tab of this repo and the [Aragon client's issues](https://github.com/aragon/aragon/issues?utf8=%E2%9C%93&q=is%3Aissue) to make sure it hasn't been reported before. Follow these steps to help us prevent duplicate issues and unnecessary notifications going to the many people watching this repo: - If the issue you found has been reported and is still open, and the details match your issue, give a "thumbs up" to the relevant posts in the issue thread to signal that you have the same issue. No further action is required on your part. - If the issue you found has been reported and is still open, but the issue is missing some details, you can add a comment to the issue thread describing the additional details. From 9b28451386fee0d92568c0a4d51be9113748a07d Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 17:06:19 +0200 Subject: [PATCH 7/8] Grammar fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e1ec21028..fd34479c80 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Running tests on all apps can be done by running `npm run test` at the root dire Running tests of an individual app can be done by running `npm run test` inside an individual app's directory, or through the selective `npm run test:` scripts. -By default, tests are run in a in-memory instance of testrpc. +By default, tests are run on an in-memory instance of testrpc. ## Contributing From a95a491be92d38f66765987733ec129f7fda9619 Mon Sep 17 00:00:00 2001 From: Brett Sun Date: Thu, 18 Jul 2019 17:06:57 +0200 Subject: [PATCH 8/8] Rename architecture tutorial link to Aragon stack --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fd34479c80..58e56794d7 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ By default, tests are run on an in-memory instance of testrpc. ## Contributing -For some introductory information on what an Aragon app is, and how to build one, please read through the [architecture introduction](https://hack.aragon.org/docs/stack) and [Your first Aragon app](https://hack.aragon.org/docs/tutorial). The [aragonAPI documentation](https://hack.aragon.org/docs/api-intro) is also available as a reference. +For some introductory information on what an Aragon app is, and how to build one, please read through the [Aragon stack introduction](https://hack.aragon.org/docs/stack) and [Your first Aragon app](https://hack.aragon.org/docs/tutorial). The [aragonAPI documentation](https://hack.aragon.org/docs/api-intro) is also available as a reference. #### 👋 Get started contributing with a [good first issue](https://github.com/aragon/aragon-apps/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).