Skip to content

Latest commit

 

History

History
69 lines (42 loc) · 4.86 KB

CONTRIBUTING.md

File metadata and controls

69 lines (42 loc) · 4.86 KB

Contributing to Concerto

We welcome contributions to Concerto!

This document explains how you should work with the Concerto repository. More information is in the 'contrib-docs' directory.

Our development process

All work on Concerto is performed on GitHub Enterprise. Changes should be developed in a fork of the Concerto repository, and the changes submitted for approval in the form of pull requests.

Workflow
Workflow diagram

develop branch

All changes and pull requests should be targeted at the develop branch. The develop branch has been configured as the default branch for the Concerto repository. When you create a pull request, a Travis CI build will automatically run to confirm that your changes build cleanly and pass all known tests. Your changes will not be merged into the develop branch unless this build runs cleanly.

master branch

We try to keep the master branch as stable as possible. Changes are regularly pushed from the develop branch up to the master branch once they have been confirmed to be good. Only specific members of the IBM Blockchain WW Labs team have permission to push to the master branch.

Testing

All changes pushed to Concerto should 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.

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.

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

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.

Pull requests

Before submitting a pull request, please make sure the following is done:

  1. Fork the repo and create your branch from develop.
  2. If you've added code that should be tested (always), add tests!
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes (npm test and go test).
  5. Make sure your code lints.

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.

Code conventions

  • 4 spaces for indentation (no tabs)
  • Prefer ' over "
  • 'use strict';
  • JSDoc comments are required