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.
contrib note update (hyperledger-archives#1279)
* contrib note update * review commens addressed
- Loading branch information
Showing
7 changed files
with
148 additions
and
42 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
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 |
|---|---|---|
| @@ -1,6 +1,83 @@ | ||
| # Contributing to Composer | ||
| * [Step-by-step developement environment setup](./contrib-notes/getting-started.md) | ||
| * [Suggested IDE setup](./contrib-notes/ide-setup.md) | ||
| * Currently reading -> [Coding Guidelines](./contrib-notes/coding-guidelines.md) | ||
| * [Pull Request Guidelines](./contrib-notes/submitting-pull-request.md) | ||
| * [Release process](./contrib-notes/release-process/weekly-qa-validation.md) | ||
|
|
||
| # Coding Guidelines | ||
|
|
||
| ## Coding Style | ||
| 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 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 eaisly achieved using the [github web-ui](https://help.github.com/articles/fork-a-repo/). | ||
| - 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 convetions and could be anything. But as in any convetion 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 | ||
| ``` | ||
| - 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 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](https://lists.hyperledger.org/mailman/listinfo/hyperledger-composer) 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 | ||
|
|
||
|
|
@@ -16,15 +93,15 @@ If you change APIs, update the documentation. Note that the linter settings will | |
|
|
||
| ## 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`. | ||
| 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/) | ||
| - [Istanbul](https://gotwarlost.github.io/istanbul/) | ||
|
|
||
| ### Unit Test Framework Using Mocha | ||
|
|
||
|
|
@@ -41,3 +118,5 @@ Hyperledger Composer tests use an assertion library called [chai](http://chaijs. | |
|
|
||
| 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. | ||
|
|
||
| # Next step | ||
| Move on to read [Pull Request Guidelines](./contrib-notes/submitting-pull-request.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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,20 @@ | ||
| # Contributing to Composer | ||
|
|
||
| * Currently reading -> [Step-by-step developement environment setup](./contrib-notes/getting-started.md) | ||
| * [Suggested IDE setup](./contrib-notes/ide-setup.md) | ||
| * [Coding Guidelines](./contrib-notes/coding-guidelines.md) | ||
| * [Pull Request Guidelines](./contrib-notes/submitting-pull-request.md) | ||
| * [Release process](./contrib-notes/release-process/weekly-qa-validation.md) | ||
|
|
||
|
|
||
| # Getting Started Developing Hyperledger Composer | ||
|
|
||
| This guide will help you start to contribute to the Hyperledger Composer project. It will show you how to set up your local environment and walk through the development, code, test and deploy process. You will do this by creating a small change of your own. | ||
|
|
||
| Please note that this is the **Getting Started** for developing Hyperledger Composer itself, and not a guide to developing applications **using** Hyperledger Composer. (Though a lot of the tool chain will be useful for that purpose as well). | ||
|
|
||
| After reading this guide, move on to reading the [coding-guidelines](./coding-guidelines.md) that will explain in more detail the process to follow to make changes. | ||
|
|
||
| ## Setup Scripts | ||
|
|
||
| The requirements for developing Hyperledger Composer are the same as developing an application using Hyperledger Composer. Follow these [instructions](./prerequisites.md) | ||
|
|
@@ -38,30 +49,19 @@ different Hyperledger Composer repositories. | |
| If this is your first Git project then you might like to spend a few moments creating a specific directory for all your local git repositories, e.g. ``~/github/`` on unix file systems, which will put the project under your home directory, which is good default location. Windows note: this will all be done in the git bash shell that was installed for you. | ||
|
|
||
| ```bash | ||
| mkdir -p ~/github | ||
| cd ~/github | ||
| $ mkdir -p ~/github | ||
| $ cd ~/github | ||
| ``` | ||
|
|
||
| _IMPORTANT_ Do NOT have any directory in the path to the git repository directory you just created, start with a _ (underscore). This is due to the way that the JavaScript documentation tool handles filtering path names. If you do this, then the tool reports there are no source files to produce documentation for. | ||
|
|
||
| The final step is to issue the clone command. This format is assuming that you have setup the ssh keys for GitHub. | ||
|
|
||
| ```bash | ||
| git clone [email protected]:<your-username>/hyperledger/composer.git | ||
| cd composer | ||
| ``` | ||
|
|
||
| ### Hyperledger Code Dependencies | ||
|
|
||
| There is a temporary requirement for Hyperledger Composer to include the Hyperledger source code in its project directory. The following commands will pull the code from the Hyperledger code repository, as defined in the `.gitmodules` file in the Hyperledger Composer project directory. | ||
|
|
||
| ```bash | ||
| git submodule init | ||
| git submodule update | ||
| $ git clone [email protected]:<your-username>/hyperledger/composer.git | ||
| $ cd composer | ||
| ``` | ||
|
|
||
| You can see where the Hyperledger source code is pulled from; it is saved in the `.git` directory of the Hyperledger Composer project. | ||
|
|
||
| ## Installing Hyperledger Composer Prerequisites | ||
|
|
||
| Hyperledger Composer has a number of prerequisites - for its runtime, code hygiene, tests, API documentation, and more. Before you can develop locally, you need to install these using [npm](https://www.npmjs.com/). These prerequisites are installed as development dependencies. The packages are installed locally rather than globally so that their versions do not interfere with other projects you may be developing or global installations of these packages on your local machine. You can also install these prerequisites globally, though it is required to have some packages locally, e.g. the test framework. | ||
|
|
@@ -70,7 +70,7 @@ Hyperledger Composer has a number of prerequisites - for its runtime, code hygie | |
|
|
||
| You must install [Lerna](https://lernajs.io) to build this multi-package repository: | ||
|
|
||
| $ npm install -g [email protected].4 | ||
| $ npm install -g [email protected].5 | ||
|
|
||
| You must bootstrap the repository so that all of the dependencies are installed and all of the packages are linked together: | ||
|
|
||
|
|
@@ -100,3 +100,9 @@ To verify that your local environment is ready for development and to confirm la | |
| $ lerna run test | ||
|
|
||
| This will run the unit tests that are associated with all the modules. | ||
|
|
||
| ## Next step | ||
| Moving on to read | ||
|
|
||
| * [Suggested IDE setup](./contrib-notes/ide-setup.md) | ||
| * [Coding Guidelines](./contrib-notes/coding-guidelines.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 was deleted.
Oops, something went wrong.
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