forked from hyperledger-archives/composer
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Contributing Guide Edits (hyperledger-archives#808)
* edits for pre-reqs * remove auto populated files * edits for pre-reqs * remove auto populated files * initial refactor of contributing * initial refactor of contributing * update naming * extend contributing * fix link * edit readme in contrib notes * add links to readme * add links to readme * re-brand * break out misc page * break out misc page
- Loading branch information
Showing
17 changed files
with
171 additions
and
185 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,49 @@ | ||
| # Contributing to Hyperledger Composer | ||
| We welcome contributions to Hyperledger Composer! | ||
|
|
||
| This document explains how you should work with the Hyperledger Composer repositories. More information is in the 'contrib-docs' directory for specific topics | ||
| We welcome contributions to the code base. There is a contributors [RocketChat channel](https://chat.hyperledger.org/channel/fabric-composer-dev) that we would encourage you to join and introduce yourself on. | ||
|
|
||
| * [Suggested ide setup](./contrib-notes/ide-setup.md) | ||
| * [Step-by-step developement environment setup](./contrib-notes/getting-started.md) | ||
|
|
||
| There is a contributors [Rocket.Chat channel](https://chat.hyperledger.org/channel/composer-dev) that it is worth introducing yourself on. | ||
|
|
||
| ## GitHub Repositories | ||
|
|
||
| The following is a list of the repositories that are part of the Hyperledger Composer project, the composer repository itself is a monorepo and holds all the source code in multiple npm modules. | ||
|
|
||
| | composer | Main monorepo with the project source code, including tests and documetnation | | ||
| | composer-sample-applications | Sample applications for Hyperledger Composer; including the 'Getting Started' tutorial | | ||
| | composer-sample-networks | Sample Hyperledger Composer Business Networks | | ||
| | composer-sample-models | Sample Hyperledger Composer Models | | ||
| | composer-atom-plugin | A syntax checker for the Atom.io editor | | ||
| | composer-vscode-plugin | A syntax checker for the VSCode editor | | ||
| | composer-tools | Tools for use with Hyperledger Composser | | ||
|
|
||
| ### Our development process | ||
| This document explains how you should work with the Composer repositories within the Hyperledger project. The repositories are: | ||
|
|
||
| The source and issue tracking system for Hyperledger Composer is [GitHub](https://github.com/hyperledger/composer). All changes should be developed in a fork of the Hyperledger Composer repository, and the changes submitted for approval in the form of pull requests. Travis-ci is used to build and test all repositories and a build is triggered when a pull request is made. Any pull request that is not 100% clean will be closed. | ||
| - [hyperledger/composer](https://github.com/hyperledger/composer) All the code, cli and documentation | ||
| - [hyperledger/composer-sample-models](https://github.com/hyperledger/composer-sample-models) Sample Business Models | ||
| - [hyperledger/composer-sample-networks](https://github.com/hyperledger/composer-sample-networks) Sample Business Networks | ||
| - [hyperledger/composer-sample-applications](https://github.com/hyperledger/composer-sample-applications) Sample Applications using the Composer API (using v0.6 Hyperledger Fabric) | ||
| - [hyperledger/composer-sample-applications-hlfv1](https://github.com/hyperledger/composer-sample-applications-hlfv1) Sample Applications using the Composer API (using v1.0.0-alpha Hyperledger Fabric). **Note this is ALPHA** | ||
| - [hyperledger/composer-atom-plugin](https://github.com/hyperledger/composer-atom-plugin) Plugin for the Atom editor | ||
| - [hyperledger/composer-vscode-plugin](https://github.com/hyperledger/composer-vscode-plugin) Plugin for the VS Code editor | ||
| - [hyperledger/composer-tools](https://github.com/hyperledger/composer-tools) Additional tools to help working with Composer | ||
|
|
||
| The master branches are currently being used, a release build is run weekly to fix the release at a new level. See the [release process](./contrib-notes/release-process.md) | ||
| ## Raising an Issue | ||
|
|
||
| ### Testing | ||
| If you have a question or problem that relates to general support, please ask the question on either [RocketChat](https://chat.hyperledger.org/channel/fabric-composer) or [Stack Overflow](http://stackoverflow.com/questions/tagged/fabric-composer), where the question should be tagged with 'fabric-composer'. We would like to exclusively use GitHub issues for bug reports and feature requests. | ||
|
|
||
| All changes pushed to Hyperledger Composer must include unit tests that ensure that the new functionality works as designed, or that fixed bugs stay fixed. Pull requests that add code changes which are not covered by automated unit tests will **not** be accepted. | ||
| If you find a bug in the source code, an error in any documentation, or would like a new feature, you can help us by [raising an issue](./contrib-notes/raising-issues.md) to our GitHub Repository or delivering a fix via a [pull request](./contrib-notes/submitting-pull-request.md). | ||
|
|
||
| Unit testing is for ensuring that small units of code *Do The Right Thing*, with an extremely quick turnaround time. An example of this might be the `AssetRegistryFactory.create()` method. The code in this method *probably* needs to do two things; send the correct invoke request to the chain-code, and correctly handle all of the possible responses from that chain-code. | ||
|
|
||
| We do not need to stand up the Hyperledger Fabric to unit test this method; we simply need to ensure that the correct calls are made to the **hfc** library. Infact, testing against a running Hyperledger Fabric can actually make this harder - especially when we need to test our code for handling errors and timeouts from the **hfc** library. It is much easier and quicker to inject errors and timeouts into a *mocked* **hfc** library. | ||
| ## Getting Started | ||
|
|
||
| Additionally, the Hyperledger team have added unit test support for chain-code. This means that chain-code can be tested as a separate unit, leading to tests such as: given world state *X*, and invoke request *Y*, is the invoke request *Y* successful and is the world state updated correctly? | ||
|
|
||
| Obviously, unit testing is not sufficient, and we do need to test the framework against a running Hyperledger Fabric to ensure that the system works as a whole. This is additional functional, system, and performance testing that should automatically be run after the unit test phase. However, these additional testing phases are not yet in place, and so are not currently documented. | ||
|
|
||
| We use **mocha** to execute our JavaScript unit tests, and these unit tests can be executed locally with `npm test`. All JavaScript code should include unit tests that can be run without requiring a running Hyperledger Fabric. Tests within composer-connector-web and composer-runtime-web use **karma** to launch a browser, and consequently **chrome** must be installed to prevent test failures. | ||
|
|
||
| <!-- We use the testing package built into Go for our Go unit tests, and these unit tests can be executed with `go test`. All Go code (primarily chain-code) should include unit tests that can be run without requiring a running Hyperledger Fabric. --> | ||
|
|
||
| Unit tests should aim for 100% code coverage. For JavaScript code, we use Istanbul is used to ensure that the unit tests meet minimum levels of code coverage. | ||
|
|
||
| ### Documentation | ||
| In order to assist anybody starting from scratch, we have produced guides on setting up an IDE and a development environment that will enable you to build and run from source: | ||
| * [Suggested IDE setup](./contrib-notes/ide-setup.md) | ||
| * [Step-by-step developement environment setup](./contrib-notes/getting-started.md) | ||
|
|
||
| We use **jsdoc** for our API documentation. If you change APIs, update the documentation. Note that the linter settings | ||
| will enforce the use of JSDoc comments for all methods and classes. We use these comments to generate high-quality | ||
| documentation and UML diagrams from source code. Please ensure your code (particularly public APIs) are clearly | ||
| documented. | ||
| Everything installed and ready code? Great! Issues are tracked in GitHub, if you are looking for a place to start with the code then it might be worth tackling a [bug](https://github.com/hyperledger/composer/issues?q=is%3Aissue+is%3Aopen+label%3Abug) or look for those issues tagged with [*help wanted*](https://github.com/hyperledger/composer/issues?q=is%3Aissue+label%3A%22help+wanted%22). | ||
|
|
||
| ### Pull requests | ||
| ## Coding Guidelines | ||
|
|
||
| *Before* submitting a pull request, please make sure the following is done: | ||
| To ensure consistency and quality through the project, we enforce rules detailed within our [Coding Guidelines](./contrib-notes/coding-guidelines.md). As a summary: | ||
|
|
||
| 1. Fork the repo and create your branch from `master`. | ||
| 2. If you've added code, add tests! | ||
| 3. If you've changed APIs, update the documentation. | ||
| 4. Ensure the test suite passes (`npm test`). | ||
| 5. Make sure your code lints. | ||
| 6. Pull requests that have associated builds that are not 100% clean will be closed. | ||
| - All changes should be developed in a fork of the relevant Hyperldger Composer repository, and the changes submitted for approval in the form of pull requests. | ||
| - All delivered code must follow the linting rules | ||
| - All features or bug fixes must be tested. | ||
| - All public API methods must be documented. | ||
| - Travis-ci is used to build and test all repositories and a build is triggered when a pull request is made. Any pull request that is not 100% clean will be closed. | ||
|
|
||
| ### Style guide | ||
|
|
||
| Our linter **eslint** will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm lint`. | ||
| ## Submitting a Pull Request | ||
|
|
||
| * 4 spaces for indentation (no tabs) | ||
| * Prefer `'` over `"` | ||
| * `'use strict';` | ||
| * JSDoc comments are required | ||
| To enable us to quickly review and accept your pull requests, always create one pull request per issue and link the issue in the pull request. Never merge multiple requests in one unless they have the same root cause. Be sure to follow our [Coding Guidelines](./contrib-notes/coding-guidelines.md) before following our [Pull Request Guidelines](./contrib-notes/submitting-pull-request.md). | ||
|
|
||
|
|
||
| ### Issue Management | ||
| Issues are tracked in Github. If you are looking for a place to start with the code then it might be worth [tackling a] defect(https://github.com/hyperledger/composer/issues?q=is%3Aissue+is%3Aopen+label%3Abug) or look for those issues tagged with [*help wanted*](https://github.com/hyperledger/composer/issues?q=is%3Aissue+label%3A%22help+wanted%22) | ||
| ## The Release | ||
|
|
||
| Please try and use the [issue template](./ISSUE_TEMPLATED.md) when raising new issues. | ||
| The master branches are currently being used as a base to cut new releases. The release process itself follows a process to ensure that the release is of suitable quallity. For more information, please see the [release process](./contrib-notes/weekly-qa-validation.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # Coding Guidelines | ||
|
|
||
| ## Coding Style | ||
|
|
||
| ### Good Coding Practices Using ESLint | ||
|
|
||
| Hyperledger Composer uses a utility to ensure the codebase conforms to good language practice. Hyperledger Composer is written in both `node.js` and `golang`, with [ESLint](http://eslint.org/) being used for `node.js`. | ||
|
|
||
| The Hyperledger Composer project includes a set of lint definitions in its initialization file ``.eslintrc.yml`` that will be used whenever lint is run, so you should use the one in the project, as it contains the default configurations. | ||
|
|
||
| ### API Documentation Using JSDoc | ||
|
|
||
| Hyperledger Composer automatically generates its API documentation from the source code with appropriate annotations using [JSDoc](https://en.wikipedia.org/wiki/JSDoc). It helps keep the API documentation up-to-date and accurate. PLEASE note the comment at the top regarding the naming of the directory path that contains the git repository. JSDoc filename filters apply to the absolute and not relative path. In summary, don't start any directory with _ | ||
|
|
||
| If you change APIs, update the documentation. Note that the linter settings will enforce the use of JSDoc comments for all methods and classes. We use these comments to generate high-quality documentation and UML diagrams from source code. Please ensure your code (particularly public APIs) are clearly documented. | ||
|
|
||
| ## Testing | ||
|
|
||
| All changes pushed to Hyperledger Composer must include unit tests that ensure that the new functionality works as designed, or that fixed bugs stay fixed. Pull requests that add code changes without associated automated unit tests will **not** be accepted. Unit tests should aim for 100% code coverage and may be run locally with `npm test`. | ||
|
|
||
| Our current test suites make use of: | ||
|
|
||
| - [Mocha](https://mochajs.org/) | ||
| - [Chai](http://chaijs.com/) | ||
| - [Karma](https://karma-runner.github.io/1.0/index.html) | ||
| - [Jasmine](https://jasmine.github.io/) | ||
| - [Istanbul](https://gotwarlost.github.io/istanbul/) | ||
|
|
||
| ### Unit Test Framework Using Mocha | ||
|
|
||
| Hyperledger Composer requires that all code added to the project is provided with unit tests. These tests operate inside a test framework called [mocha](https://mochajs.org/) which controls their execution. Mocha is triggered every time code is pushed to either a user's repository or the Hyperledger Composer repository. | ||
|
|
||
| ### Unit Test Framework using Karma and Jasmine | ||
| The default configuration is set to target the Chrome browser, and this is the target browser during the build process. Unit tests should rigorously test controller files and where appropriate inspect the view to ensure that mapped logic is operating as expected. | ||
|
|
||
| ### Simplify writing tests using the chai assertion library, chai-things and sinon | ||
|
|
||
| Hyperledger Composer tests use an assertion library called [chai](http://chaijs.com/) to help write these tests, which run in the mocha. Chai allows developers to easily write tests that verify the behaviour of their code using `should`, `expect` and `assert` interfaces. [chai-things](https://www.npmjs.com/package/chai-things) is a chai extension which helps writing units tests involving arrays. Hyperledger Composer sometimes relies on external systems like Hyperledger and to enable the creation of unit tests, Hyperledger Composer [sinon](https://www.npmjs.com/package/sinon) to create realistic units tests which do not draw in huge amounts of infrastructure. sinon has technology called "test spies", "stubs" and "mocks" which greatly help this process. | ||
|
|
||
| ### Code Coverage Using Istanbul | ||
|
|
||
| The Hyperledger Composer project uses a code coverage tool called [Istanbul](https://gotwarlost.github.io/istanbul/) to ensure that all the code is tested, including statements, branches and functions. This helps to improve the quality of the Hyperledger Composer tests. The output of Istanbul can be used to see where any specific tests need to be added to ensure complete code coverage. | ||
|
|
Oops, something went wrong.