diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55805c9017..758916fa1f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,28 +26,15 @@ If you find a bug in the source code, an error in any documentation, or would li ## Getting Started -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) - -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). - -## Coding Guidelines - -To ensure consistency and quality through the project, we enforce rules detailed within our [Coding Guidelines](./contrib-notes/coding-guidelines.md). As a summary: +In order to assist anybody starting from scratch, we have produced guides on setting up a a development environment. - - 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. - - -## Submitting a Pull Request - -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). +* [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) -## The Release +Start with the [Step-by-step developement environment setup](./contrib-notes/getting-started.md) -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/release-process/weekly-qa-validation.md) \ No newline at end of file +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). diff --git a/README.md b/README.md index 430f77e49b..830b8a3f4e 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ We welcome contributions to the code base. If you are interested in becoming a c - [raising an issue](/contrib-notes/raising-issues.md) - [submitting a pull request](/contrib-notes/submitting-pull-request.md) -There is a [specific channel](https://chat.hyperledger.org/channel/composer-dev) on RocketChat for contributors* +There is a [specific channel](https://chat.hyperledger.org/channel/composer-dev) on RocketChat for contributors. # Getting started with building an application @@ -32,3 +32,16 @@ Suggested reading list is: - [Quick Start](https://hyperledger.github.io/composer/installing/quickstart.html) - [Quick Start Video](https://www.youtube.com/watch?v=pEHBIfb_iqc&t=5s) - [Tutorials](https://hyperledger.github.io/composer/tutorials/tutorialindex.html) + +# Getting in touch + +If you have a *question on using Hyperledger Composer* + - Rocket.Chat [discussion channels](https://chat.hyperledger.org/channel/composer) + - [Stack Overflow](http://stackoverflow.com/questions/tagged/hyperledger-composer), where the question should be tagged with 'hyperledger-composer'. + +If you have found a defect or want to raise a feature requests + - All tracked on Github - please read [how to raise](./contrib-notes/raising-issues,md) + +If you want to contribute to the develop of Hyperledger Composer + - Come introduce yourself on the contributors [RocketChat channel](https://chat.hyperledger.org/channel/composer-dev) + - Please read the [contributing guide](./CONTRIBUTING.md) diff --git a/contrib-notes/coding-guidelines.md b/contrib-notes/coding-guidelines.md index d41db81956..e046795e8e 100644 --- a/contrib-notes/coding-guidelines.md +++ b/contrib-notes/coding-guidelines.md @@ -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 git@github.com: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 git@github.com: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,7 +93,7 @@ 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: @@ -24,7 +101,7 @@ Our current test suites make use of: - [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) diff --git a/contrib-notes/getting-started.md b/contrib-notes/getting-started.md index 8add933bc8..16503a71c3 100644 --- a/contrib-notes/getting-started.md +++ b/contrib-notes/getting-started.md @@ -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,8 +49,8 @@ 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. @@ -47,21 +58,10 @@ _IMPORTANT_ Do NOT have any directory in the path to the git repository director 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 git@github.ibm.com:/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 git@github.com:/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 lerna@2.0.0-rc.4 + $ npm install -g lerna@2.0.0-rc.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) diff --git a/contrib-notes/ide-setup.md b/contrib-notes/ide-setup.md index 5e2e40b985..f08a333221 100644 --- a/contrib-notes/ide-setup.md +++ b/contrib-notes/ide-setup.md @@ -1,3 +1,10 @@ +# Contributing to Composer +* [Step-by-step developement environment setup](./contrib-notes/getting-started.md) +* Currently reading -> [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) + # IDE setup for Hyperledger Composer development Both Atom.io and VS Code are popular editors amongst the Hyperledger Composer contributors. @@ -32,3 +39,7 @@ Use the [file-icons plugin](https://atom.io/packages/file-icons) to assign visua # Using VSCode _to do_ + +# Next step + +Move on to read [Coding Guidelines](./contrib-notes/coding-guidelines.md) diff --git a/contrib-notes/readme.md b/contrib-notes/readme.md deleted file mode 100644 index 8672b281de..0000000000 --- a/contrib-notes/readme.md +++ /dev/null @@ -1 +0,0 @@ -To start development of Hyperledger Composer, please follow out [getting started guide](./getting-started.md). \ No newline at end of file diff --git a/contrib-notes/submitting-pull-request.md b/contrib-notes/submitting-pull-request.md index 86f619b883..51631fc64d 100644 --- a/contrib-notes/submitting-pull-request.md +++ b/contrib-notes/submitting-pull-request.md @@ -1,3 +1,11 @@ +# Contributing to Composer +* [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) +* Currently reading -> [Pull Request Guidelines](./contrib-notes/submitting-pull-request.md) +* [Release process](./contrib-notes/release-process/weekly-qa-validation.md) + + # Submitting a Pull Request *Before* submitting a pull request, please search carefully for any open or closed pull requests that relate to the issue you are targetting. @@ -7,3 +15,6 @@ - Ensure that all test suites pass locally (`npm test`). - Commit any changes using a descriptive commit message. - Pull requests that have associated builds that are not 100% clean will be closed. + +# Next step +Move on to read [Release process](./contrib-notes/release-process/weekly-qa-validation.md)