Merge "docs: add arch overview and refactor home page"

docs/CONTRIBUTING.md

@@ -78,6 +78,14 @@ the `lf-sandbox`
 you should be ready to set up your local development
 [environment](dev-setup/devenv.md).
 
+Next, try [building the project](dev-setup/build.md) in your local development
+environment to ensure that everything is set up correctly.
+
+[Logging control](Setup/logging-control.md) describes how to tweak the logging
+levels of various components within the Fabric. Finally, every source file
+needs to include a [license header](dev-setup/headers.txt): modified to include
+a copyright statement for the principle author(s).
+
 ## What makes a good change request?
 
 * One change at a time. Not five, not three, not ten. One and only one. Why?
@@ -138,8 +146,24 @@ getting it merged and adds more work for you - to remediate the merge conflicts.
 
 ## 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.
+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.
+
+## Communication <a name="communication"></a>
+
+We use [RocketChat](https://chat.hyperledger.org/) for communication and
+Google Hangouts&trade; for screen sharing between developers. Our development
+planning and prioritization is done in [JIRA](https://jira.hyperledger.org),
+and we take longer running discussions/decisions to the
+[mailing list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric).
+
+## 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).
 
 ### Becoming a maintainer
 

docs/architecture.md

@@ -0,0 +1,99 @@
+Hyperledger Fabric is a unique implementation of distributed ledger technology
+(DLT) that ensures data integrity and consistency while delivering
+accountability, transparency, and efficiencies unmatched by other blockchain
+or DLT technology.
+
+Hyperledger Fabric implements a specific type of
+[permissioned](glossary.md#permissioned-network)
+[blockchain network](glossary.md#blockchain-network) on which members can
+track, exchange and interact with digitized assets using
+[transactions](glossary.md#transactions) that are governed by smart
+contracts - what we call [chaincode](glossary.md#chaincode) - in a secure and
+robust manner while enabling [participants](glossary.md#participants) in the
+network to interact in a manner that ensures that their transactions and data
+can be restricted to an identified subset of network participants - something
+we call a [channel](glossary.md#channel).
+
+The blockchain network supports the ability for members to establish
+shared ledgers that contain the source of truth about those digitized
+assets, and recorded transactions, that is replicated in a secure manner only
+to the set of nodes participating in that channel.
+
+The Hyperledger Fabric architecture is comprised of the following components:
+peer nodes, ordering nodes and the clients applications that are likely
+leveraging one of the language-specific Fabric SDKs. These components have
+identities derived from certificate authorities. Hyperledger Fabric also
+offers a certificate authority service, *fabric-ca* but, you may substitute
+that with your own.
+
+All peer nodes maintain the ledger/state by committing
+transactions. In that role, the peer is called a
+[committer](glossary.md#committer). Some peers are also responsible for
+simulating transactions by executing chaincodes (smart contracts) and endorsing
+the result. In that role the peer is called an [endorser](glossary.md#endorser).
+A peer may be an endorser for certain types of transactions and just a ledger
+maintainer (committer) for others.
+
+The [orderers](glossary.md#orderer) consent on the order of transactions in a
+block to be committed to the ledger. In common blockchain architectures
+(including earlier versions of the Hyperledger Fabric) the roles played by
+the peer and orderer nodes were unified (cf. validating peer in Hyperledger
+Fabric v0.6). The orderers also play a fundamental role in the creation and
+management of channels.
+
+Two or more [participants](glossary.md#participant) may create and join a
+channel, and begin to interact. Among other things, the policies governing the
+channel membership and chaincode lifecycle are specified at the time of
+channel creation. Initially, the members in a channel agree on
+the terms of the chaincode that will govern the transactions. When consensus
+is reached on the [proposal](glossary.md#proposal) to deploy a given chaincode
+(as governed by the life cycle policy for the channel), it is committed to
+the ledger.
+
+Once the chaincode is deployed to the peer nodes in the channel,
+[end users](glossary.md#end-users) with the right privileges can propose
+transactions on the channel by using one of the language-specific client SDKs
+to invoke functions on the deployed chaincode.
+
+The proposed transactions are sent to endorsers that execute the chaincode
+(also called "simulated the transaction"). On successful execution, endorse
+the result using the peer's identity and return the result to the client that
+initiated the proposal.
+
+The client application ensures that the results from the endorsers are
+consistent and signed by the appropriate endorsers, according to the endorsement
+policy for that chaincode and, if so, the application then sends the transaction,
+comprised of the result and endorsements, to the ordering service. 
+
+Ordering nodes order the transactions - the result and endorsements received
+from the clients - into a block which is then sent to the peer nodes to be
+committed to the ledger. The peers then validate the transaction using the
+endorsement policy for the transaction's chaincode and against the ledger for
+consistency of result.
+
+Some key capabilities of Hyperledger Fabric include:
+
+- Allows for complex query for applications that need ability to handle complex
+data structures.
+
+- Implements a permissioned network, also known as a consortia network, where
+all members are known to each other.
+
+- Incorporates a modular approach to various capabilities, enabling network
+designers to plug in their preferred implementations for various capabilities
+such as consensus (ordering), identity management, and encryption.
+
+- Provides a flexible approach for specifying policies and pluggable mechanisms
+to enforce them.
+
+- Ability to have multiple channels, isolated from one another, that
+allows for multi-lateral transactions amongst select peer nodes, thereby
+ensuring high degrees of privacy and confidentiality required by competing
+businesses and highly regulated industries on a common network.
+
+- Network scalability and performance are achieved through separation of
+chaincode execution from transaction ordering, which limits the required levels
+of trust and verification across nodes for optimization.
+
+For a deeper dive into the details, please visit
+[this document](arch-deep-dive.md).