diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 01348099fb7..00000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ -### Welcome - -We welcome contributions to the Hyperledger Project in many forms, and there's always plenty to do! - -First things first, please review the Hyperledger Project's [Code of Conduct](https://github.com/hyperledger/hyperledger/wiki/Hyperledger-Project-Code-of-Conduct) before participating. It is important that we keep things civil. - -### Getting help -If you are looking for something to work on, or need some expert assistance in debugging a problem or working out a fix to an issue, our [community](https://www.hyperledger.org/community) is always eager to help. We hang out on [Slack](https://hyperledgerproject.slack.com/), IRC (#hyperledger on freenode.net) and the [mailing lists](http://lists.hyperledger.org/). Most of us don't bite ;-) and will be glad to help. - -### Requirements and Use Cases -We have a [Requirements WG](https://github.com/hyperledger/hyperledger/wiki/Requirements-WG) that is documenting use cases and from those use cases deriving requirements. If you are interested in contributing to this effort, please feel free to join the discussion in [slack](https://hyperledgerproject.slack.com/messages/requirements/). - -### Reporting bugs -If you are a user and you find a bug, please submit an [issue](https://github.com/hyperledger/fabric/issues). Please try to provide sufficient information for someone else to reproduce the issue. One of the project's maintainers should respond to your issue within 24 hours. If not, please bump the issue and request that it be reviewed. - -### Fixing issues and working stories -Review the [issues list](https://github.com/hyperledger/fabric/issues) and find something that interests you. You could also check the ["help wanted"](https://github.com/hyperledger/fabric/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) list. It is wise to start with something relatively straight forward and achievable. Usually there will be a comment in the issue that indicates whether someone has already self-assigned the issue. If no one has already taken it, then add a comment assigning the issue to yourself, eg.: ```I'll work on this issue.```. Please be considerate and rescind the offer in comments if you cannot finish in a reasonable time, or add a comment saying that you are still actively working the issue if you need a little more time. - -We are using the [GitHub Flow](https://guides.github.com/introduction/flow/) process to manage code contributions. If you are unfamiliar, please review that link before proceeding. - -To work on something, whether a new feature or a bugfix: - 1. Create a [fork](https://help.github.com/articles/fork-a-repo/) (if you haven't already) - - 2. Clone it locally - ``` - git clone https://github.com/yourid/fabric.git - ``` - - 3. Add the upstream repository as a remote - ``` - git remote add upstream https://github.com/hyperledger/fabric.git - ``` - - 4. Create a branch - Create a descriptively-named branch off of your cloned fork ([more detail here](https://help.github.com/articles/syncing-a-fork/)) - ``` - cd fabric - git checkout -b issue-nnnn - ``` - - 5. Commit your code - - Commit to that branch locally, and regularly push your work to the same branch on the server. - - 6. Commit messages - - Commit messages must have a short description no longer than 50 characters followed by a blank line and a longer, more descriptive message that includes reference to issue(s) being addressed so that they will be automatically closed on a merge e.g. ```Closes #1234``` or ```Fixes #1234```. - - 7. Pull Request (PR) - - **Note:** Each source file must include a license header for the Apache Software License 2.0. A template of that header can be found [here](https://github.com/hyperledger/fabric/blob/master/docs/dev-setup/headers.txt). - - When you need feedback or help, or you think the branch is ready for merging, open a pull request (make sure you have first successfully built and tested with the [Unit and Behave Tests](docs/dev-setup/install.md#3-test)). - - _Note: if your PR does not merge cleanly, use ```git rebase master``` in your feature branch to update your pull request rather than using ```git merge master```_. - - 8. Did we mention tests? All code changes should be accompanied by new or modified tests. - - 9. Continuous Integration (CI): Be sure to check [Travis](https://travis-ci.org/) or the Slack [#fabric-ci-status](https://hyperledgerproject.slack.com/messages/fabric-ci-status) channel for status of your build. You can re-trigger a build on [Jenkins](https://jenkins.io/) with a PR comment containing `reverify jenkins`. - - **Note:** While some underlying work to migrate the build system from Travis to Jenkins is taking place, you can ask the [maintainers](https://github.com/hyperledger/fabric/blob/master/MAINTAINERS.txt) to re-trigger a Travis build for your PR, either by adding a comment to the PR or on the [#fabric-ci-status](https://hyperledgerproject.slack.com/messages/fabric-ci-status) Slack channel. - - 10. Any code changes that affect documentation should be accompanied by corresponding changes (or additions) to the documentation and tests. This will ensure that if the merged PR is reversed, all traces of the change will be reversed as well. - -After your Pull Request (PR) has been reviewed and signed off, a maintainer will merge it into the master branch. - -## Coding guidelines - -### Coding Golang -- We code in Go™ and strictly follow the [best practices](http://golang.org/doc/effective_go.html) -and will not accept any deviations. You must run the following tools against your Go code and fix all errors and warnings: - - [golint](https://github.com/golang/lint) - - [go vet](https://golang.org/cmd/vet/) - - [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) - - ## Generating gRPC code - - If you modify any `.proto` files, run the following command to generate/update the respective `.pb.go` files. - - ``` - cd $GOPATH/src/github.com/hyperledger/fabric - make protos - ``` - - ## Adding or updating Go packages - - The Hyperledger Fabric Project uses Go 1.6 vendoring for package management. This means that all required packages reside in the `vendor` folder within the fabric project. Go will use packages in this folder instead of the GOPATH when the `go install` or `go build` commands are executed. To manage the packages in the `vendor` folder, we use [Govendor](https://github.com/kardianos/govendor), which is installed in the Vagrant environment. The following commands can be used for package management: - - ``` - # Add external packages. - govendor add +external - - # Add a specific package. - govendor add github.com/kardianos/osext - - # Update vendor packages. - govendor update +vendor - - # Revert back to normal GOPATH packages. - govendor remove +vendor - - # List package. - govendor list - ``` - -### Becoming a maintainer -This project is managed under open governance model as described in our [charter](https://www.hyperledger.org/about/charter). Projects or sub-projects will be lead by a set of maintainers. New projects can designate an initial set of maintainers that will be approved by the Technical Steering Committee when the project is first approved. The project's maintainers will, from time-to-time, consider adding or removing a maintainer. An existing maintainer will post a pull request to the [MAINTAINERS.txt](MAINTAINERS.txt) file. If a majority of the maintainers concur in the comments, the pull request is then merged and the individual becomes a (or is removed as a) maintainer. Note that removing a maintainer should not be taken lightly, but occasionally, people do move on - hence the bar should be some period of inactivity, an explicit resignation, some infraction of the code of conduct or consistently demonstrating poor judgement. - -### Legal stuff - -**Note:** Each source file must include a license header for the Apache Software License 2.0. A template of that header can be found [here](https://github.com/hyperledger/fabric/blob/master/docs/dev-setup/headers.txt). - -We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. We use the same approach—the [Developer's Certificate of Origin 1.1 (DCO)](docs/biz/DCO1.1.txt)—that the Linux® Kernel [community](http://elinux.org/Developer_Certificate_Of_Origin) uses to manage code contributions. -We simply ask that when submitting a pull request, the developer must include a sign-off statement in the pull request description. - -Here is an example Signed-off-by line, which indicates that the submitter accepts the DCO: - -``` -Signed-off-by: John Doe -``` diff --git a/MAINTAINERS.txt b/MAINTAINERS.txt deleted file mode 100644 index d06ad68f664..00000000000 --- a/MAINTAINERS.txt +++ /dev/null @@ -1,11 +0,0 @@ -Maintainers - -Binh Nguyen binhn binhn@us.ibm.com -Sheehan Anderson srderson sheehan@us.ibm.com -Tamas Blummer tamasblummer tamas@digitalasset.com -Robert Fajta rfajta robert@digitalasset.com -Greg Haskins ghaskins ghaskins@lseg.com -Jonathan Levi JonathanLevi jonathan@levi.name -Gabor Hosszu gabre gabor@digitalasset.com -Simon Schubert corecode sis@zurich.ibm.com -Chris Ferris christo4ferris chrisfer@us.ibm.com diff --git a/README.md b/README.md deleted file mode 100644 index c93a211b031..00000000000 --- a/README.md +++ /dev/null @@ -1,41 +0,0 @@ -[![Build Status](https://travis-ci.org/hyperledger/fabric.svg?branch=master)](https://travis-ci.org/hyperledger/fabric) -[![Go Report Card](https://goreportcard.com/badge/github.com/hyperledger/fabric)](https://goreportcard.com/report/github.com/hyperledger/fabric) -[![GoDoc](https://godoc.org/github.com/hyperledger/fabric?status.svg)](https://godoc.org/github.com/hyperledger/fabric) -[![Documentation Status](https://readthedocs.org/projects/hyperledger-fabric/badge/?version=latest)](http://hyperledger-fabric.readthedocs.io/en/latest/?badge=latest) - -# Incubation Notice -This project is a Hyperledger project in _Incubation_. It was proposed to the community and documented [here](https://goo.gl/RYQZ5N). Information on what _Incubation_ entails can be found in the [Hyperledger Project Lifecycle document](https://goo.gl/4edNRc). - -# Hyperledger Fabric -The fabric is an implementation of blockchain technology, leveraging familiar and proven technologies. It is a modular architecture allowing pluggable implementations of various function. It features powerful container technology to host any mainstream language for smart contracts development. - -## Releases -The fabric releases are documented [here](https://github.com/hyperledger/fabric/wiki/Fabric-Releases). We have just released our first release under the governance of the Hyperledger Project - v0.5-developer-preview. - -## Contributing to the project -We welcome contributions to the Hyperledger Project in many forms. There's always plenty to do! Full details of how to contribute to this project are documented in the [CONTRIBUTING.md](CONTRIBUTING.md) file. - -## Maintainers -The project's [maintainers](MAINTAINERS.txt): are responsible for reviewing and merging all pull requests and they guide the over-all technical direction of the project within the guidelines established by the Hyperledger Project's Technical Steering Committee (TSC). - -## Communication -We use [Hyperledger Slack](https://slack.hyperledger.org/) for communication and Google Hangouts™ for screen sharing between developers. - -## Installing the fabric -[Installation](docs/Setup/Network-setup.md): Describes how to install the blockchain fabric and use project tools. - -## Documentation -Project documentation can be found [here](http://hyperledger-fabric.readthedocs.io/en/latest/). - -## Still Have Questions? -For general purpose questions, please use [StackOverflow](http://stackoverflow.com/questions/tagged/hyperledger). - -## License -The Hyperledger Project uses the [Apache License Version 2.0](LICENSE) software license. - -## Related information -If you are new to the project, you can begin by reviewing the following documents: - - - [Whitepaper WG](https://github.com/hyperledger/hyperledger/wiki/Whitepaper-WG) - - [Requirements WG](https://github.com/hyperledger/hyperledger/wiki/Requirements-WG) - - [Protocol Specification](docs/protocol-spec.md) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000000..92102988acd --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Contributions Welcome! + +We welcome contributions to the Hyperledger Project in many forms, and +there's always plenty to do! + +First things first, please review the Hyperledger Project's [Code of +Conduct](https://github.com/hyperledger/hyperledger/wiki/Hyperledger-Project-Code-of-Conduct) +before participating. It is important that we keep things civil. + +## Getting a Linux Foundation account + +In order to participate in the development of the Hyperledger Fabric project, +you will need an [LF account](Gerrit/lf-account.md). This will give you single +sign-on to all the community tools, including Gerrit and Jira (coming soon!). + +## Getting help + +If you are looking for something to work on, or need some expert assistance in +debugging a problem or working out a fix to an issue, our +[community](https://www.hyperledger.org/community) is always eager to help. We +hang out on [Slack](https://hyperledgerproject.slack.com/), IRC (#hyperledger on +freenode.net) and the [mailing lists](http://lists.hyperledger.org/). Most of us +don't bite ;-) and will be glad to help. + +## Requirements and Use Cases + +We have a [Requirements +WG](https://github.com/hyperledger/hyperledger/wiki/Requirements-WG) that is +documenting use cases and from those use cases deriving requirements. If you are +interested in contributing to this effort, please feel free to join the +discussion in +[slack](https://hyperledgerproject.slack.com/messages/requirements/). + +## Reporting bugs + +If you are a user and you find a bug, please submit an +[issue](https://github.com/hyperledger/fabric/issues). Please try to provide +sufficient information for someone else to reproduce the issue. One of the +project's maintainers should respond to your issue within 24 hours. If not, +please bump the issue and request that it be reviewed. + +## Fixing issues and working stories +Review the [issues list](https://github.com/hyperledger/fabric/issues) and find +something that interests you. You could also check the ["help +wanted"](https://github.com/hyperledger/fabric/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) +and ["good first +bug"](https://github.com/hyperledger/fabric/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-bug) +lists. It is wise to start with something relatively straight forward and +achievable. Usually there will be a comment in the issue that indicates whether +someone has already self-assigned the issue. If no one has already taken it, +then add a comment assigning the issue to yourself, eg.: `I'll work on this +issue.`. Please be considerate and rescind the offer in comments if you cannot +finish in a reasonable time, or add a comment saying that you are still actively +working the issue if you need a little more time. + +## Working with a local clone and Gerrit + +We are using [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric) +to manage code contributions. If you are unfamiliar, please review [this +document](Gerrit/gerrit.md) before proceeding. + +After you have familiarized yourself with `Gerrit`, and maybe played around with +the `lf-sandbox` project, you should be ready to set up your local [development +environment](dev-setup/devenv.md). We use a Vagrant-based approach to +development that simplifies things greatly. + +## Coding guidelines + +Be sure to check out the language-specific [style +guides](Style-guides/go-style.md) before making any changes. This will ensure a +smoother review. + +### Becoming a maintainer + +This project is managed under open governance model as described in our +[charter](https://www.hyperledger.org/about/charter). Projects or sub-projects +will be lead by a set of maintainers. New projects can designate an initial set +of maintainers that will be approved by the Technical Steering Committee when +the project is first approved. The project's maintainers will, from +time-to-time, consider adding or removing a maintainer. An existing maintainer +will post a patchset to the [MAINTAINERS.md](MAINTAINERS.md) file. If a +majority of the maintainers concur in the comments, the pull request is then +merged and the individual becomes a (or is removed as a) maintainer. Note that +removing a maintainer should not be taken lightly, but occasionally, people do +move on - hence the bar should be some period of inactivity, an explicit +resignation, some infraction of the code of conduct or consistently +demonstrating poor judgement. + +## Legal stuff + +**Note:** Each source file must include a license header for the Apache Software +License 2.0. A template of that header can be found [here](https://github.com/hyperledger/fabric/blob/master/docs/dev-setup/headers.txt). + +We have tried to make it as easy as possible to make contributions. This +applies to how we handle the legal aspects of contribution. We use the same +approach—the [Developer's Certificate of Origin 1.1 (DCO)](docs/biz/DCO1.1.txt)—that +the Linux® Kernel [community](http://elinux.org/Developer_Certificate_Of_Origin) uses to manage code contributions. + +We simply ask that when submitting a patch for review, the developer must include +a sign-off statement in the commit message. + +Here is an example Signed-off-by line, which indicates that the submitter +accepts the DCO: + +``` +Signed-off-by: John Doe +``` +You can include this automatically when you commit a change to your local git +repository using `git commit -s`. diff --git a/docs/Gerrit/best-practices.md b/docs/Gerrit/best-practices.md new file mode 100644 index 00000000000..ed9da5ce831 --- /dev/null +++ b/docs/Gerrit/best-practices.md @@ -0,0 +1,337 @@ +# Gerrit Recommended Practices + +This document presents some best practices to help you use Gerrit more +effectively. The intent is to show how content can be submitted easily. Use the +recommended practices to reduce your troubleshooting time and improve +participation in the community. + +## Browsing the Git Tree + +Visit [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric) then +select `Projects --> List --> SELECT-PROJECT --> Branches`. Select the branch +that interests you, click on `gitweb` located on the right-hand side. Now, +`gitweb` loads your selection on the Git web interface and redirects +appropriately. + +## Watching a Project + +Visit [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric), then +select `Settings`, located on the top right corner. Select `Watched Projects` +and then add any projects that interest you. + +## Commit Messages + +Gerrit follows the Git commit message format. Ensure the headers are at the +bottom and don't contain blank lines between one another. The following example +shows the format and content expected in a commit message: + + Brief (no more than 50 chars) one line description. + + Elaborate summary of the changes made referencing why (motivation), what was +changed and how it was tested. Note also any changes to documentation made to +remain consistent with the code changes, wrapping text at 72 chars/line. + + Jira: FAB-100 + Change-Id: LONGHEXHASH + Signed-off-by: Your Name your.email@example.org + AnotherExampleHeader: An Example of another Value + +The Gerrit server provides a precommit hook to autogenerate the Change-Id which +is one time use. + +**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) + +## Avoid Pushing Untested Work to a Gerrit Server + +To avoid pushing untested work to Gerrit. + +Check your work at least three times before pushing your change to Gerrit. +Be mindful of what information you are publishing. + +## Keeping Track of Changes + +- Set Gerrit to send you emails: + + - Gerrit will add you to the email distribution list for a change if a + developer adds you as a reviewer, or if you comment on a specific Patch + Set. + +- Opening a change in Gerrit's review interface is a quick way to follow that + change. + +- Watch projects in the Gerrit projects section at `Gerrit`, select at least + *New Changes, New Patch Sets, All Comments* and *Submitted Changes*. + +Always track the projects you are working on; also see the feedback/comments +mailing list to learn and help others ramp up. + +## Topic branches + +Topic branches are temporary branches that you push to commit a set of +logically-grouped dependent commits: + +To push changes from `REMOTE/master` tree to Gerrit for being reviewed as +a topic in **TopicName** use the following command as an example: + + $ git push REMOTE HEAD:refs/for/master/TopicName + +The topic will show up in the review :abbr:`UI` and in the +`Open Changes List`. Topic branches will disappear from the master +tree when its content is merged. + +## Creating a Cover Letter for a Topic + +You may decide whether or not you'd like the cover letter to appear in the +history. + +1. To make a cover letter that appears in the history, use this command: + +``` +git commit --allow-empty +``` + +Edit the commit message, this message then becomes the cover letter. +The command used doesn't change any files in the source tree. + +2. To make a cover letter that doesn't appear in the history follow these steps: + + - Put the empty commit at the end of your commits list so it can be ignored + without having to rebase. + + - Now add your commits + +``` +git commit ... +git commit ... +git commit ... +``` + + - Finally, push the commits to a topic branch. The following command is an + example: + +``` +git push REMOTE HEAD:refs/for/master/TopicName +``` + +If you already have commits but you want to set a cover letter, create an empty +commit for the cover letter and move the commit so it becomes the last commit +on the list. Use the following command as an example: + +``` +git rebase -i HEAD~#Commits +``` + +Be careful to uncomment the commit before moving it. +`#Commits` is the sum of the commits plus your new cover letter. + + +## Finding Available Topics + +``` + $ ssh -p 29418 gerrit.hyperledger.org gerrit query \ status:open project:fabric branch:master \ + | grep topic: | sort -u +``` + +- [gerrit.hyperledger.org]() Is the current URL where the project is hosted. +- *status* Indicates the topic's current status: open , merged, abandoned, draft, +merge conflict. +- *project* Refers to the current name of the project, in this case fabric. +- *branch* The topic is searched at this branch. +- *topic* The name of an specific topic, leave it blank to include them all. +- *sort* Sorts the found topics, in this case by update (-u). + +## Downloading or Checking Out a Change + +In the review UI, on the top right corner, the **Download** link provides a +list of commands and hyperlinks to checkout or download diffs or files. + +We recommend the use of the *git review* plugin. +The steps to install git review are beyond the scope of this document. +Refer to the [git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) for the installation process. + +To check out a specific change using Git, the following command usually works: + +``` +git review -d CHANGEID +``` + +If you don't have Git-review installed, the following commands will do the same +thing: + +``` +git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD +``` + +For example, for the 4th version of change 2464, NN is the first two digits +(24): + +``` +git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD +``` + +## Using Draft Branches + +You can use draft branches to add specific reviewers before you publishing your +change. The Draft Branches are pushed to `refs/drafts/master/TopicName` + +The next command ensures a local branch is created: + +``` +git checkout -b BRANCHNAME +``` + +The next command pushes your change to the drafts branch under **TopicName**: + +``` +git push REMOTE HEAD:refs/drafts/master/TopicName +``` + +## Using Sandbox Branches + +You can create your own branches to develop features. The branches are pushed to +the `refs/sandbox/USERNAME/BRANCHNAME` location. + +These commands ensure the branch is created in Gerrit's server. + +``` +git checkout -b sandbox/USERNAME/BRANCHNAME +git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME +``` + +Usually, the process to create content is: + +- develop the code, +- break the information into small commits, +- submit changes, +- apply feedback, +- rebase. + +The next command pushes forcibly without review: + +``` +git push REMOTE sandbox/USERNAME/BRANCHNAME +``` + +You can also push forcibly with review: + +``` +git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME +``` + +## Updating the Version of a Change + +During the review process, you might be asked to update your change. It is +possible to submit multiple versions of the same change. Each version of the +change is called a patch set. + +Always maintain the **Change-Id** that was assigned. +For example, there is a list of commits, **c0...c7**, which were submitted as a +topic branch: + +``` +git log REMOTE/master..master + +c0 +... +c7 + +git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +After you get reviewers' feedback, there are changes in **c3** and **c4** that +must be fixed. If the fix requires rebasing, rebasing changes the commit Ids, +see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section +for more information. However, you must keep the same Change-Id and push the +changes again: + +``` +git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +This new push creates a patches revision, your local history is then cleared. +However you can still access the history of your changes in Gerrit on the +`review UI` section, for each change. + +It is also permitted to add more commits when pushing new versions. + +## Rebasing + +Rebasing is usually the last step before pushing changes to Gerrit; this allows +you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same. + +- **squash:** mixes two or more commits into a single one. +- **reword:** changes the commit message. +- **edit:** changes the commit content. +- **reorder:** allows you to interchange the order of the commits. +- **rebase:** stacks the commits on top of the master. + +## Rebasing During a Pull + +Before pushing a rebase to your master, ensure that the history has a +consecutive order. + +For example, your `REMOTE/master` has the list of commits from **a0** to +**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: + +``` +git log --oneline REMOTE/master..master + +a0 +a1 +a2 +a3 +a4 +c0 +c1 +... +c7 +``` + +If `REMOTE/master` receives commits **a5**, **a6** and **a7**. Pull with a +rebase as follows: + +``` +git pull --rebase REMOTE master +``` + +This pulls **a5-a7** and re-apply **c0-c7** on top of them: + + +``` + $ git log --oneline REMOTE/master..master + a0 + ... + a7 + c0 + c1 + ... + c7 +``` + +## Getting Better Logs from Git + +Use these commands to change the configuration of Git in order to produce better +logs: + +``` +git config log.abbrevCommit true +``` + +The command above sets the log to abbreviate the commits' hash. + +``` +git config log.abbrev 5 +``` + +The command above sets the abbreviation length to the last 5 characters of the +hash. + +``` +git config format.pretty oneline +``` + +The command above avoids the insertion of an unnecessary line before the Author +line. + +To make these configuration changes specifically for the current Git user, +you must add the path option `--global` to `config` as follows: diff --git a/docs/Gerrit/changes.md b/docs/Gerrit/changes.md new file mode 100644 index 00000000000..840735aa280 --- /dev/null +++ b/docs/Gerrit/changes.md @@ -0,0 +1,60 @@ +# Submitting a Change to Gerrit + +Carefully review the following before submitting a change. These +guidelines apply to developers that are new to open source, as well as +to experienced open source developers. + +## Change Requirements + +This section contains guidelines for submitting code changes for review. +For more information on how to submit a change using Gerrit, please +see [Gerrit](gerrit.md). + +Changes are submitted as Git commits. Each commit must contain: + +- a short and descriptive subject line that is 72 characters or fewer, + followed by a blank line. +- a change description with your logic or reasoning for the changes, + followed by a blank line +- a Signed-off-by line, followed by a colon (Signed-off-by:) +- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't + accept patches without this identifier. + +A commit with the above details is considered well-formed. + +All changes and topics sent to Gerrit must be well-formed. Informationally, +`commit messages` must include: + +* **what** the change does, +* **why** you chose that approach, and +* **how** you know it works -- for example, which tests you ran. + +Commits must [build cleanly](../dev-setup/build.md) when applied in top of each +other, thus avoiding breaking bisectability. Each commit must address a single +identifiable issue and must be logically self-contained. + +For example: One commit fixes whitespace issues, another renames a +function and a third one changes the code's functionality. An example commit +file is illustrated below in detail: + +``` +Updating tables presentation. + +Tables were misaligned; fixed spacing. + +Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 +Signed-off-by: Your Name commit-sender@email.address +``` +Each commit must contain the following line at the bottom of the commit +message: + +``` +Signed-off-by: Your Name your@email.address +``` + +The name in the Signed-off-by line and your email must match the change +authorship information. Make sure your :file:`.git/config` is set up +correctly. Always submit the full set of changes via Gerrit. + +When a change is included in the set to enable other changes, but it +will not be part of the final set, please let the reviewers know this. diff --git a/docs/Gerrit/gerrit.md b/docs/Gerrit/gerrit.md new file mode 100644 index 00000000000..04d6e5cb69f --- /dev/null +++ b/docs/Gerrit/gerrit.md @@ -0,0 +1,198 @@ +# Working with Gerrit + +Follow these instructions to collaborate on the Hyperledger Fabric Project +through the Gerrit review system. + +Please be sure that you are subscribed to the [mailing +list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric) and of +course, you can reach out on [Slack](https://hyperledgerproject.slack.com/) if +you need help. + +Gerrit assigns the following roles to users: + +* **Submitters**: May submit changes for consideration, review other code + changes, and make recommendations for acceptance or rejection by voting + +1 or -1, respectively. +* **Maintainers**: May approve or reject changes based upon feedback from + reviewers voting +2 or -2, respectively. +* **Builders**: (e.g. Jenkins) May use the build automation infrastructure to + verify the change. + +Maintainers should be familiar with the [review process](reviewing.md). However, +anyone is welcome to (and encouraged!) review changes, and hence may find that +document of value. + +## Git-review + +There's a **very** useful tool for working with Gerrit called +[git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This +command-line tool can automate most of the ensuing sections for you. Of course, +reading the information below is also highly recommended so that you understand +what's going on behind the scenes. + +## Sandbox project + +We have created a [sandbox +project](https://gerrit.hyperledger.org/r/#/admin/projects/lf-sandbox) to allow +developers to familiarize themselves with Gerrit and our workflows. Please do +feel free to use this project to experiment with the commands and tools, below. + +## Getting deeper into Gerrit + +A comprehensive walk-through of Gerrit is beyond the scope of this document. +There are plenty of resources available on the Internet. A good summary can be +found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial). We have also +provided a set of [Best Practices](best-practices.md) that you may find helpful. + +## Working with a local clone of the repository + +To work on something, whether a new feature or a bugfix: + +1. Open the Gerrit [Projects page](https://gerrit.hyperledger.org/r/#/admin/projects/) + +2. Select the project you wish to work on. + +3. Open a terminal window and clone the project locally using the `Clone with git +hook` URL. Be sure that `ssh` is also selected, as this will make authentication +much simpler: +``` +git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/ +``` + +**Note:** if you are cloning the fabric project repository, you will want to +clone it to the `$GOPATH/src/github.com/hyperledger` directory so that it will +build, and so that you can use it with the Vagrant [development +environment](../dev-setup/devenv.md). + +4. Create a descriptively-named branch off of your cloned repository + +``` +cd fabric +git checkout -b issue-nnnn +``` + +5. Commit your code. For an in-depth discussion of creating an effective commit, +please read [this document](changes.md). + +``` +git commit -s +``` + +6. Any code changes that affect documentation should be accompanied by +corresponding changes (or additions) to the documentation and tests. This +will ensure that if the merged PR is reversed, all traces of the change will +be reversed as well. + +## Submitting a Change + +Currently, Gerrit is the only method to submit a change for review. **Please review +the [guidelines](changes.md) for making and submitting a change**. + +**Note:** if you prefer, you can use the [git-review](#git-review) tool instead +of the following. e.g. + +``` +cd +git review -R +``` + +Directions for building the source code can be found [here](../dev-setup/build.md). + +When a change is ready for submission, Gerrit requires that the +change be pushed to a special branch. The name of this special branch +contains a reference to the final branch where the code should reside, +once accepted. + +For the Hyperledger Fabric Project, the special branch is called `refs/for/master`. + +To push the current local development branch to the gerrit server, open a +terminal window at the root of your cloned repository: + +``` +cd +git push origin HEAD:refs/for/master +``` +If the command executes correctly, the output should look similar to this: + +``` +Counting objects: 3, done. +Writing objects: 100% (3/3), 306 bytes | 0 bytes/s, done. +Total 3 (delta 0), reused 0 (delta 0) +remote: Processing changes: new: 1, refs: 1, done +remote: +remote: New Changes: +remote: https://gerrit.hyperledger.org/r/6 Test commit +remote: +To ssh://LFID@gerrit.hyperledger.org:29418/fabric +* [new branch] HEAD -> refs/for/master +``` + +The gerrit server generates a link where the change can be tracked. + +## Adding reviewers + +Optionally, you can add reviewers to your change. + +To specify a list of reviewers via the command line, add +`%r=reviewer@project.org` to your push command. For example: + +``` +git push origin HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com +``` + Alternatively, you can auto-configure GIT to add a set of reviewers if your + commits will have the same reviewers all at the time. + + To add a list of default reviewers, open the :file:`.git/config` file in the + project directory and add the following line in the `[ branch “master” ]` + section: + +``` +[branch "master"] #.... push = +HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com` +``` + +Make sure to use actual email addresses instead of the `@email.com and @notemail.com` +addressses. Don't forget to replace `origin` with your git remote name. + +## Reviewing Using Gerrit + +* **Add**: This button allows the change submitter to manually add names of + people who should review a change; start typing a name and the system + will auto-complete based on the list of people registered and with + access to the system. They will be notified by email that you are + requesting their input. + +* **Abandon**: This button is available to the submitter only; it allows a + committer to abandon a change and remove it from the merge queue. + +* **Change-ID**: This ID is generated by Gerrit (or system). It becomes + useful when the review process determines that your commit(s) have to + be amended. You may submit a new version; and if the same Change-ID + header (and value) are present, Gerrit will remember it and present + it as another version of the same change. + +* **Status**: Currently, the example change is in review status, as indicated + by “Needs Verified” in the upper-left corner. The list of + Reviewers will all emit their opinion, voting +1 if they agree to the + merge, -1 if they disagree. Gerrit users with a Maintainer role can + agree to the merge or refuse it by voting +2 or -2 respectively. + +Notifications are sent to the email address in your commit message's +Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.hyperledger.org/r/#/dashboard/self), to check the progress of your requests. + +The history tab in Gerrit will show you the in-line comments and the author of +the review. + +## Viewing Pending Changes + +Find all pending changes by clicking on the `All --> Changes` link in the +upper-left corner, or [open this link](https://gerrit.1.org/r/#/q/project:fabric). + +If you collaborate in multiple projects, you may wish to limit searching to +the specific branch through the search bar in the upper-right side. + +Add the filter *project:fabric* to limit the visible changes to +only those from the Hyperledger Fabric Project. + +List all current changes you submitted, or list just those changes in need +of your input by clicking on `My --> Changes` or [open this link](https://gerrit.hyperledger.org/r/#/dashboard/self) diff --git a/docs/Gerrit/lf-account.md b/docs/Gerrit/lf-account.md new file mode 100644 index 00000000000..57787431eb9 --- /dev/null +++ b/docs/Gerrit/lf-account.md @@ -0,0 +1,106 @@ +# Requesting a Linux Foundation Account + +Contributions to the Fabric code base require a Linux Foundation account. +Follow the steps below to create a Linux Foundation account. + +## Creating a Linux Foundation ID + +1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/). + +1. Select the option `I need to create a Linux Foundation ID`. + +1. Fill out the form that appears: + +1. Open your email account and look for a message with the subject line: + "Validate your Linux Foundation ID email". + +1. Open the received URL to validate your email address. + +1. Verify the browser displays the message `You have successfully + validated your e-mail address`. + +1. Access `Gerrit` by selecting `Sign In`: + +1. Use your Linux Foundation ID to Sign In: + +## Configuring Gerrit to Use SSH + +Gerrit uses SSH to interact with your Git client. A SSH private key +needs to be generated on the development machine with a matching public +key on the Gerrit server. + +If you already have a SSH key-pair, skip this section. + +As an example, we provide the steps to generate the SSH key-pair on a Linux +environment. Follow the equivalent steps on your OS. + +1. Create a key-pair, enter: + +``` +ssh-keygen -t rsa -C "John Doe john.doe@example.com" +``` + +**Note:** This will ask you for a password to protect the private key as it +generates a unique key. Please keep this password private, and DO NOT +enter a blank password. + +The generated key-pair is found in: `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`. + +1. Add the private key in the `id_rsa` file in your key ring, e.g.: + +``` +ssh-add ~/.ssh/id_rsa +``` + +Once the key-pair has been generated, the public key must be added to Gerrit. + +Follow these steps to add your public key `id_rsa.pub` to the Gerrit +account: + +1. Go to [Gerrit](https://gerrit.hyperledger.org/r/#/admin/projects/fabric). + +1. Click on your account name in the upper right corner. + +1. From the pop-up menu, select `Settings`. + +1. On the left side menu, click on `SSH Public Keys`. + +1. Paste the contents of your public key `~/.ssh/id_rsa.pub` and click + `Add key`. + +**Note:** The `id_rsa.pub` file can be opened with any text editor. Ensure + that all the contents of the file are selected, copied and pasted into the + `Add SSH key` window in Gerrit. + +**Note:** The ssh key generation instructions operate on the assumtion that +you are using the default naming. It is possible to generate multiple ssh Keys +and to name the resulting files differently. See the [ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) +documentation for details on how to do that. Once you have generated non-default +keys, you need to configure ssh to use the correct key for Gerrit. In that case, +you need to create a `~/.ssh/config` file modeled after the one below. + +``` +host gerrit.hyperledger.org + HostName gerrit.hyperledger.org + IdentityFile ~/.ssh/id_rsa_hyperledger_gerrit + User +``` +where is your Linux Foundation ID and the value of IdentityFile is the +name of the public key file you generated. + +**Warning:** Potential Security Risk! Do not copy your private key + `~/.ssh/id_rsa` Use only the public `~/.ssh/id_rsa.pub`. + +## Checking Out the Source Code + +1. Ensure that SSH has been set up properly. See + `Configuring Gerrit to Use SSH` for details. + +1. Clone the repository with your Linux Foundation ID (): + +``` +git clone ssh://@gerrit.hyperledger.org:29418/fabric fabric +``` + +You have successfully checked out a copy of the source code to your local +machine. diff --git a/docs/Gerrit/reviewing.md b/docs/Gerrit/reviewing.md new file mode 100644 index 00000000000..79fafe8f27b --- /dev/null +++ b/docs/Gerrit/reviewing.md @@ -0,0 +1,51 @@ +# Reviewing a Change + +1. Click on a link for incoming or outgoing review. + +2. The details of the change and its current status are loaded: + + * **Status:** Displays the current status of the change. In the + example below, the status reads: Needs Verified. + + * **Reply:** Click on this button after reviewing to add a final + review message and a score, -1, 0 or +1. + + * **Patch Sets:** If multiple revisions of a patch exist, this button + enables navigation among revisions to see the changes. By default, + the most recent revision is presented. + + * **Download:** This button brings up another window with multiple + options to download or checkout the current changeset. The button on + the right copies the line to your clipboard. You can easily paste it + into your git interface to work with the patch as you prefer. + + Underneath the commit information, the files that have been changed by + this patch are displayed. + +3. Click on a filename to review it. Select the code base to differentiate + against. The default is `Base` and it will generally be + what is needed. + +4. The review page presents the changes made to the file. At the top of + the review, the presentation shows some general navigation options. + Navigate through the patch set using the arrows on the top + right corner. It is possible to go to the previous or next file in the + set or to return to the main change screen. Click on the yellow sticky + pad to add comments to the whole file. + + The focus of the page is on the comparison window. The changes made + are presented in green on the right versus the base version on the left. + Double click to highlight the text within the actual change to provide + feedback on a specific section of the code. Press *c* once the code is + highlighted to add comments to that section. + +5. After adding the comment, it is saved as a *Draft*. + +6. Once you have reviewed all files and provided feedback, click the + *green up arrow* at the top right to return to the main change page. Click + the `Reply` button, write some final comments, and submit your score for + the patch set. Click `Post` to submit the review of each reviewed file, as + well as your final comment and score. Gerrit sends an email to the + change-submitter and all listed reviewers. Finally, it logs the review + for future reference. All individual comments are saved as *Draft* until + the `Post` button is clicked. diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md new file mode 100644 index 00000000000..ec2273c0ff2 --- /dev/null +++ b/docs/MAINTAINERS.md @@ -0,0 +1,13 @@ +## Maintainers + +| Name | GitHub | Gerrit | email | +|---|---|---|---| +| Binh Nguyen | binhn | | binhn@us.ibm.com | +| Sheehan Anderson | srderson || sheehan@us.ibm.com +| Tamas Blummer | tamasblummer || tamas@digitalasset.com +| Robert Fajta | rfajta || robert@digitalasset.com +| Greg Haskins | ghaskins || ghaskins@lseg.com +| Jonathan Levi | JonathanLevi || jonathan@levi.name +| Gabor Hosszu | gabre || gabor@digitalasset.com +| Simon Schubert | corecode || sis@zurich.ibm.com +| Chris Ferris | christo4ferris | ChristopherFerris | chrisfer@us.ibm.com diff --git a/docs/Style-guides/go-style.md b/docs/Style-guides/go-style.md new file mode 100644 index 00000000000..dc5f08902cb --- /dev/null +++ b/docs/Style-guides/go-style.md @@ -0,0 +1,48 @@ +## Coding guidelines + +### Coding Golang + +We code in Go™ and strictly follow the [best +practices](http://golang.org/doc/effective_go.html) and will not accept any +deviations. You must run the following tools against your Go code and fix all +errors and warnings: + - [golint](https://github.com/golang/lint) + - [go vet](https://golang.org/cmd/vet/) + - [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) + +## Generating gRPC code + +If you modify any `.proto` files, run the following command to generate/update +the respective `.pb.go` files. + +``` +cd $GOPATH/src/github.com/hyperledger/fabric +make protos +``` + +## Adding or updating Go packages + +The Hyperledger Fabric Project uses Go 1.6 vendoring for package management. +This means that all required packages reside in the `vendor` folder within the +fabric project. Go will use packages in this folder instead of the GOPATH when +the `go install` or `go build` commands are executed. To manage the packages in +the `vendor` folder, we use [Govendor](https://github.com/kardianos/govendor), +which is installed in the Vagrant environment. The following commands can be +used for package management: + +``` + # Add external packages. + govendor add +external + + # Add a specific package. + govendor add github.com/kardianos/osext + + # Update vendor packages. + govendor update +vendor + + # Revert back to normal GOPATH packages. + govendor remove +vendor + + # List package. + govendor list +``` diff --git a/docs/dev-setup/devenv.md b/docs/dev-setup/devenv.md index 9a18b348169..c12a70b943e 100644 --- a/docs/dev-setup/devenv.md +++ b/docs/dev-setup/devenv.md @@ -35,17 +35,21 @@ git config --global core.autocrlf false ``` If you continue with `core.autocrlf` set to `true`, the `vagrant up` command will fail with the error `./setup.sh: /bin/bash^M: bad interpreter: No such file or directory` -#### Cloning the Peer project +#### Cloning the Fabric project -Create a fork of the [fabric](https://github.com/hyperledger/fabric) repository using the GitHub web interface. Next, clone your fork in the appropriate location. +Since the Fabric project is a `Go` project, you'll need to clone the Fabric repo to your $GOPATH/src directory. If your $GOPATH has multiple path components, then you will want to use the first one. There's a little bit of setup needed: ``` cd $GOPATH/src mkdir -p github.com/hyperledger cd github.com/hyperledger -git clone https://github.com//fabric.git ``` +Recall that we are using `Gerrit` for source control, which has its own internal git repositories. Hence, we will need to [clone from Gerrit](../Gerrit/gerrit.md#Working-with-a-local-clone-of-the-repository). For brevity, the command is as follows: +``` +git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/ +``` +**Note:** of course, you would want to replace `LFID` with your [Linux Foundation ID](../Gerrit/lf-account.md). #### Boostrapping the VM using Vagrant @@ -67,7 +71,7 @@ Once you have your vagrant development environment established, you can proceed ### Notes -**NOTE:** any time you `git clone` any of the projects in your Host's fabric directory (under $GOPATH/src/github.com/hyperledger/fabric), the update will be instantly available within the VM fabric directory. +**NOTE:** any time you change any of the files in your local fabric directory (under `$GOPATH/src/github.com/hyperledger/fabric`), the update will be instantly available within the VM fabric directory. **NOTE:** If you intend to run the development environment behind an HTTP Proxy, you need to configure the guest so that the provisioning process may complete. You can achieve this via the *vagrant-proxyconf* plugin. Install with `vagrant plugin install vagrant-proxyconf` and then set the VAGRANT_HTTP_PROXY and VAGRANT_HTTPS_PROXY environment variables *before* you execute `vagrant up`. More details are available here: https://github.com/tmatilai/vagrant-proxyconf/ diff --git a/docs/index.md b/docs/index.md index 5af4103d926..28d1ca1dde8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,52 +1,155 @@ -## Hyperledger Fabric Documentation -The Hyperledger [fabric](https://github.com/hyperledger/fabric) is an implementation of blockchain technology, that has been collaboratively developed under the Linux Foundation's [Hyperledger Project](http://hyperledger.org). It leverages familiar and proven technologies, and offers a modular architecture that allows pluggable implementations of various function including membership services, consensus, and smart contracts (Chaincode) execution. It features powerful container technology to host any mainstream language for smart contracts development. +# Incubation Notice -To contribute to this documentation, create an issue for any requests for clarification or to highlight any errors, or you may fork and update the [source](https://github.com/hyperledger/fabric), and submit a pull request. +This project is a Hyperledger project in _Incubation_. It was proposed to the +community and documented [here](https://goo.gl/RYQZ5N). Information on what +_Incubation_ entails can be found in the [Hyperledger Project Lifecycle +document](https://goo.gl/4edNRc). + +[![Go Report Card](https://goreportcard.com/badge/github.com/hyperledger/fabric)](https://goreportcard.com/report/github.com/hyperledger/fabric) +[![GoDoc](https://godoc.org/github.com/hyperledger/fabric?status.svg)](https://godoc.org/github.com/hyperledger/fabric) +[![Documentation Status](https://readthedocs.org/projects/hyperledger-fabric/badge/?version=latest)](http://hyperledger-fabric.readthedocs.io/en/latest/?badge=latest) + +# Hyperledger Fabric + +The fabric is an implementation of blockchain technology, leveraging familiar +and proven technologies. It is a modular architecture allowing pluggable +implementations of various function. It features powerful container technology +to host any mainstream language for smart contracts development. + +## Releases + +The fabric releases are documented +[here](https://github.com/hyperledger/fabric/wiki/Fabric-Releases). We have just +released our first release under the governance of the Hyperledger Project - +v0.5-developer-preview. + +## Contributing to the project + +We welcome contributions to the Hyperledger Project in many forms. There's +always plenty to do! Full details of how to contribute to this project are +documented in the [Fabric developer's guide](#fabric-developer-guide) below. + +To contribute to this documentation, create an issue for any requests for +clarification or to highlight any errors, or you may clone and update the +[source](https://gerrit.hyperledger.org/r/#/admin/projects/fabric), and submit a +Gerrit review (essentially the same process as for fabric development). + +## Maintainers + +The project's [maintainers](MAINTAINERS.md): are responsible for reviewing and +merging all patches submitted for review and they guide the over-all technical +direction of the project within the guidelines established by the Hyperledger +Project's Technical Steering Committee (TSC). + +## Communication + +We use [Hyperledger Slack](https://slack.hyperledger.org/) for communication and +Google Hangouts™ for screen sharing between developers. + +# Hyperledger Fabric Documentation + +The Hyperledger +[fabric](https://gerrit.hyperledger.org/r/#/admin/projects/fabric) is an +implementation of blockchain technology, that has been collaboratively developed +under the Linux Foundation's [Hyperledger Project](http://hyperledger.org). It +leverages familiar and proven technologies, and offers a modular architecture +that allows pluggable implementations of various function including membership +services, consensus, and smart contracts (Chaincode) execution. It features +powerful container technology to host any mainstream language for smart +contracts development. + +## Still Have Questions? +We try to maintain a comprehensive set of documentation for various audiences. +However, we realize that often there are questions that remain unanswered. For +any technical questions relating to the Hyperledger Fabric project not answered +in this documentation, please use +[StackOverflow](http://stackoverflow.com/questions/tagged/hyperledger). + +## TOC Below, you'll find the following sections: - [Getting started](#getting-started) - [Quickstart](#quickstart-documentation) -- Developer guides - - [Fabric developer guide](#fabric-developer-guide) - - [Chaincode developer guide](#chaincode-developer-guide) - - [API developer guide](#api-developer-guide) +- [Developer guides](#developer-guides) + + - [Fabric developer's guide](#fabric-developer-guide) + - [Chaincode developer's guide](#chaincode-developer-guide) + - [API developer's guide](#api-developer-guide) + - [Operations guide](#operations-guide) -## Getting started +# Getting started -If you are new to the project, you can begin by reviewing the following links. If you'd prefer to dive right in, see the [Quickstart](#quickstart-documentation) section, below. +If you are new to the project, you can begin by reviewing the following links. +If you'd prefer to dive right in, see the +[Quickstart](#quickstart-documentation) section, below. -- [Whitepaper WG](https://github.com/hyperledger/hyperledger/wiki/Whitepaper-WG): where the community is developing a whitepaper to explain the motivation and goals for the project. -- [Requirements WG](https://github.com/hyperledger/hyperledger/wiki/Requirements-WG): where the community is developing use cases and requirements. +- [Whitepaper WG](https://github.com/hyperledger/hyperledger/wiki/Whitepaper-WG): +where the community is developing a whitepaper to explain the motivation and +goals for the project. +- [Requirements WG](https://github.com/hyperledger/hyperledger/wiki/Requirements-WG): +where the community is developing use cases and requirements. - [Canonical use cases](biz/usecases.md) -- [Glossary](glossary.md): to understand the terminology that we use throughout the Fabric project's documentation. +- [Glossary](glossary.md): to understand the terminology that we use throughout +the Fabric project's documentation. - [Fabric FAQs](https://github.com/hyperledger/fabric/tree/master/docs/FAQ) -## Quickstart documentation +# Quickstart documentation -- [Development environment set-up](dev-setup/devenv.md): if you are considering helping with development of the Hyperledger Fabric or Fabric-API projects themselves, this guide will help you install and configure all you'll need. The development environment is also useful (but, not necessary) for developing blockchain applications and/or Chaincode. -- [Network setup](Setup/Network-setup.md): This document covers setting up a network on your local machine for development. -- [Chaincode development environment](Setup/Chaincode-setup.md): Chaincode developers need a way to test and debug their Chaincode without having to set up a complete peer network. This document describes how to write, build, and test Chaincode in a local development environment. -- [APIs](API/CoreAPI.md): This document covers the available APIs for interacting with a peer node. +- [Development environment set-up](dev-setup/devenv.md): if you are considering +helping with development of the Hyperledger Fabric or Fabric-API projects +themselves, this guide will help you install and configure all you'll need. The +development environment is also useful (but, not necessary) for developing +blockchain applications and/or Chaincode. +- [Network setup](Setup/Network-setup.md): This document covers setting up a +network on your local machine for development. +- [Chaincode development environment](Setup/Chaincode-setup.md): Chaincode +developers need a way to test and debug their Chaincode without having to set up +a complete peer network. This document describes how to write, build, and test +Chaincode in a local development environment. +- [APIs](API/CoreAPI.md): This document covers the available APIs for +interacting with a peer node. -## Fabric developer guide +# Developer guides -When you are ready to start contributing to the Hyperledger fabric project, we strongly recommend that you read the [protocol specification](protocol-spec.md) for the technical details so that you have a better understanding of how the code fits together. +## Fabric developer guide -- [Making code contributions](https://github.com/hyperledger/fabric/blob/master/CONTRIBUTING.md): First, you'll want to familiarize yourself with the project's contribution guidelines. -- [Setting up the development environment](dev-setup/devenv.md): after that, you will want to set up your development environment. -- [Building the fabric core](dev-setup/build.md): next, try building the project in your local development environment to ensure that everything is set up correctly. -- [Building outside of Vagrant](dev-setup/build.md#building-outside-of-vagrant): for the adventurous, you might try to build outside of the standard Vagrant development environment. -- [Logging control](Setup/logging-control.md): describes how to tweak the logging levels of various components within the fabric. -- [License header](dev-setup/headers.txt): every source file must include this license header modified to include a copyright statement for the principle author(s). +When you are ready to start contributing to the Hyperledger fabric project, we +strongly recommend that you read the [protocol specification](protocol-spec.md) +for the technical details so that you have a better understanding of how the +code fits together. + +- [Making code contributions](CONTRIBUTING.md): First, you'll want to familiarize +yourself with the project's contribution guidelines. +- [Setting up the development environment](dev-setup/devenv.md): after that, you +will want to set up your development environment. +- [Building the fabric core](dev-setup/build.md): next, try building the project +in your local development environment to ensure that everything is set up +correctly. +- [Building outside of Vagrant](dev-setup/build.md#building-outside-of-vagrant): +for the adventurous, you might try to build outside of the standard Vagrant +development environment. +- [Logging control](Setup/logging-control.md): describes how to tweak the logging +levels of various components within the fabric. +- [License header](dev-setup/headers.txt): every source file must include this +license header modified to include a copyright statement for the principle +author(s). ## Chaincode developer guide -- [Setting up the development environment](dev-setup/devenv.md): when developing and testing Chaincode, or an application that leverages the fabric API or SDK, you'll probably want to run the fabric locally on your laptop to test. You can use the same setup that Fabric developers use. -- [Setting Up a Network For Development](Setup/Network-setup.md): alternately, you can follow these instructions for setting up a local network for Chaincode development without the entire fabric development environment setup. -- [Writing, Building, and Running Chaincode in a Development Environment](Setup/Chaincode-setup.md): a step-by-step guide to writing and testing Chaincode. -- [Chaincode FAQ](FAQ/chaincode_FAQ.md): a FAQ for all of your burning questions relating to Chaincode. +- [Setting up the development environment](dev-setup/devenv.md): when developing +and testing Chaincode, or an application that leverages the fabric API or SDK, +you'll probably want to run the fabric locally on your laptop to test. You can +use the same setup that Fabric developers use. +- [Setting Up a Network For Development](Setup/Network-setup.md): alternately, you +can follow these instructions for setting up a local network for Chaincode +development without the entire fabric development environment setup. +- [Writing, Building, and Running Chaincode in a Development +Environment](Setup/Chaincode-setup.md): a step-by-step guide to writing and +testing Chaincode. +- [Chaincode FAQ](FAQ/chaincode_FAQ.md): a FAQ for all of your burning questions +relating to Chaincode. ## API developer guide @@ -55,8 +158,15 @@ When you are ready to start contributing to the Hyperledger fabric project, we s - [REST](API/CoreAPI.md#rest-api): working with the REST API. - [Node.js SDK](https://github.com/hyperledger/fabric/blob/master/sdk/node/README.md): working with the Node.js SDK. -## Operations guide +# Operations guide -- [Setting Up a Network](Setup/Network-setup.md): instructions for setting up a network of fabric peers. -- [Certificate Authority (CA) Setup](Setup/ca-setup.md): setting up a CA to support identity, security (authentication/authorization), privacy and confidentiality. +- [Setting Up a Network](Setup/Network-setup.md): instructions for setting up a +network of fabric peers. +- [Certificate Authority (CA) Setup](Setup/ca-setup.md): setting up a CA to +support identity, security (authentication/authorization), privacy and +confidentiality. - [Application ACL](tech/application-ACL.md): working with access control lists. + +## License +The Hyperledger Project uses the [Apache License Version 2.0](LICENSE) software +license. diff --git a/mkdocs.yml b/mkdocs.yml index 248bd916a65..b81da566fdc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ site_name: Hyperledger Fabric site_url: http://hyperledger-fabric.readthedocs.io theme: readthedocs -repo_url: https://github.com/hyperledger/fabric +repo_url: http://gerrit.hyperledger.org/r/fabric site_description: 'Welcome to the Hyperledger fabric documentation' pages: @@ -10,9 +10,7 @@ pages: - Protocol Spec: protocol-spec.md - Usecases: biz/usecases.md -- Setup: - - Fabric Developer Setup: dev-setup/devenv.md - - Building Fabric: dev-setup/build.md +- Installation and setup: - Chaincode or Application Developer Setup: Setup/Chaincode-setup.md - Java Chaincode Setup: Setup/JAVAChaincode.md - Fabric Network Setup: Setup/Network-setup.md @@ -20,12 +18,25 @@ pages: - CA Setup: Setup/ca-setup.md - Logging: Setup/logging-control.md -- API: +- APIs: - Chaincode APIs: API/ChaincodeAPI.md - Core API: API/CoreAPI.md - CA API: API/MemberServicesAPI.md - System Chaincode: SystemChaincodes/noop.md +- Fabric Developer: + - Contributing: CONTRIBUTING.md + - Getting an Account: Gerrit/lf-account.md + - Gerrit: Gerrit/gerrit.md + - Fabric Developer Setup: dev-setup/devenv.md + - Building Fabric: dev-setup/build.md + - Best Practices: Gerrit/best-practices.md + - Maintainers: MAINTAINERS.md + - Reviewing: Gerrit/reviewing.md + - Changes: Gerrit/changes.md + - Style guides: + - Golang: Style-guides/go-style.md + - FAQ: - ChainCodeFAQ: FAQ/chaincode_FAQ.md - ConfidentialityFAQ: FAQ/confidentiality_FAQ.md