Skip to content

Latest commit

 

History

History
152 lines (114 loc) · 10.1 KB

coding-guidelines.md

File metadata and controls

152 lines (114 loc) · 10.1 KB
Raw

Contributing to Composer

Coding Guidelines

As a summary:

  • 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 commits require DCO sign-off
  • All pull request must be linked to an issue
  • 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.

GitHub usage

Here is the preferred workflow involved in making a pull request to the Composer Project - this is based around making a change in the hyperledger/composer repository. The same would apply for any of the other related repositories.

A first step is ensuring that you have a local development environment configured.

  • You must fork the hyperledger/composer repository to your own github organization. This is most easily achieved using the github web-ui.
  • Once forked you can clone this repository to your local machine
$ git clone [email protected]:MyGitName/composer.git
  • This will configure the origin to be your fork of the Composer repository. You must create an upstream target to refer to main Composer repository. [the terms origin and upstream are conventions and could be anything. But as in any convention the purpose is to avoid confusion]
$ git remote add upstream [email protected]:hyperledger/composer.git

  • As this is just forked it will be up-to-date. But if you did this previously and now starting on something new, the the next step is to update your master branch.

    This is the point you would come to generally when starting anything new, a new clone/fork everytime is not necassary

$ git checkout master       # puts you into master branch if not there already
$ git pull upstream master  # gets all the changes from the upstream master
  • The piece of work you are starting on could be a defect, new feature, or something experimental. The approach is the same for any these and requires working in a new branch.
$ git checkout -b defect-1234    # Including reference to the git issue is useful

  • As you commit changes to your local repository ensure you provide sign-off for that commit using the -s option of git commit. For more information see https://github.com/probot/dco#how-it-works

  • Time passes, and you now have a change that you are happy with. Next step is to push this to your local repository. First step is to ensure that your branch is update.

$ git pull upstream master

You might at this point need to do manual merges.

  • Retest to ensure everthing is Good
  • Push these changes to your local fork
$ git push origin defect-1234   # note the branch you have been working on
  • The next step is to go to the Github web-ui and create a pull request to the master repository for this fork.
  • ...screen shots needed here - wip...
  • All Pull Requests should be linked to the issue they are addressing
  • All Pull Requests should have a review by another comitter on the Composer project
  • Any API, CLI, or major change should be mentioned to a maintainer to ensure consistency

Important Reminders

  • NEVER work in your master branch
  • Should this occur, then the master branch will need to be reset using this command
$ git reset --hard upstream/master && curl -O site://hursley-house/topfloor/penguin.penance

Development approach

Adding new Features

We welcome contributions of new features. Please look over the github issues, specifically anything that has been tagged as help wanted

When you start working on new issue, please do the following:

  • Use the mailing list to notify the community that you are planning to start feature work and notify that the design has been placed in the GitHub issue
    • this is to ensure that there is a persistent record of what is happening
  • Say hello, on the composer-dev channel on RocketChat
  • At noteable points please join the weekly community call to share what you have done.

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

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

How to run local code inside a real fabric

When fabric builds the image for the chaincode container, it does this by doing an npm install against the package.json of the package composer-runtime-hlfv1. This presents a problem as it pulls the code base that has been published to the npm registry rather than your local code base. To be able to work with your latest code base you need to run the fabric peer in development mode. The following provides steps by example on how to do this.

  • Ensure you have the latest fabric-dev-servers package and have set your fabric runtime to V1.1 export FABRIC_VERSION=hlfv11
  • Start the fabric in development mode using the -d or --dev option. eg ./startFabric.sh -d
  • create and import your PeerAdmin card if you haven't done so before eg ./createPeerAdmin.sh
  • Open a command window and change to the packages/composer-runtime-hlfv1 directory
  • Start the Composer chaincode with an appropriate business network name and version of the composer-runtime-hlfv1 (The version you need is the version defined in the package.json of the composer-runtime-hlfv1 package. In this example I have shown a version number of 0.17.0) eg.
CORE_CHAINCODE_ID_NAME="mynetwork:0.17.0" node start.js --peer.address grpc://localhost:7052
  • install a composer runtime package (note this doesn't get used but has to be present on the peer) Assuming you are still in the composer-runtime-hlfv1 directory eg.
node ../composer-cli/cli.js runtime install -n mynetwork -c PeerAdmin@hlfv1
  • instantiate the chaincode, this will drive your running node process you started earlier.
node cli.js network start -a mynetwork.bna -c PeerAdmin@hlfv1 -A admin -S adminpw

You should now see output in the window running the chaincode showing it executing.

Next step

Move on to read Pull Request Guidelines