Add directory structure and introduction for the development document…

…ation (#1400)

Signed-off-by: Attila Klenik <a.klenik@gmail.com>

dev-docs/README.md

@@ -0,0 +1,33 @@
+# Hyperledger Caliper Developer Documentation
+
+## Overview
+
+The current documentation gives an in-depth technical insight into the design and internal workings of Hyperledger Caliper. The aim of this document is to make contributions to the code-base easier and provide a basis for discussing architectural changes and enhancements - in the form of proposals.
+
+## Contributing to the document
+
+The document is split into multiple parts, following the main modules of Caliper. This allows the figures to target specific modules and their interactions instead of being all cluttered (resembling reverse-engineered figures) by containing everything.
+
+The contributions to the current development documentation (this README) follows the traditional [contributing guide](./../CONTRIBUTING.md). Figures (e.g., class and sequence diagrams) are core building block of this documentation. In order to allow the meaningful version control of figures, [PlantUML](https://plantuml.com/) is used to create them. Every new figure source (the `.puml` file) and its resulting PNG output must be placed into the `dev-docs/figures` directory. 
+
+> The [PlantUML VSCode extension](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml) is a convenient tool to edit and quickly visualize `puml` files. It can also generate the required PNG outputs. Moreover, the current directory contains a `generate-figure.sh` script that uses a containerized version of PlantUML to generate the selected figure next to its source. Usage example (from the current directory): `generate-figure.sh ./figures/worker-classes.puml`. Note that [Docker](https://docs.docker.com/engine/install/) is required to run the script.
+
+## Proposals
+
+Larger architectural changes (i.e., not just minor, local refactorings) first must be proposed in the form of a separate document. The document must: 
+1. Provide a short overview of the proposed changes.
+1. Detail the shortcomings of the current architecture, i.e., why the changes are necessary and what are their benefits.
+1. Identify the affected parts of Caliper.
+1. Detail the proposed changes to the code-base.
+1. Discuss the potential breaking changes in the APIs.
+1. Split the proposed changes into smaller work items if possible.
+
+The proposals must be placed into the `dev-docs/proposals` directory following the traditional [contributing guide](./../CONTRIBUTING.md). The proposal file names must follow the `<PR number>-<short proposal title>` format. The `proposals/0000-proposal-template.md` file serves as the template for new proposals. Copy and rename the file to start working on a proposal. The practice for including figures in a proposal is the same as for this document. 
+
+> You must prefix your figure sources and outputs with the PR number of the proposal, so figures of different proposal don't get mixed. To avoid guessing the PR number, you can first open an empty draft PR then continue your work using that PR number. That way the project maintainers will also be aware of the planned proposal and can aid you from the start (possibly avoiding potentially major revisions later on).
+
+The content of the proposals will be discussed among the maintainers and contributor mainly in the form of PR comments and reviews. The proposal is deemed accepted once the corresponding PR is merged. Once the content of the proposal has been implemented, then the corresponding documentation and figures must be incorporated into the main developer documentation.
+
+## Table of contents
+
+> The developer documentation is work in progress. Available contents are (will be) listed below.

dev-docs/generate-figure.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+if [ $# -eq 0 ] ; then
+    echo "ERROR: PUML file path argument is missing! Usage: generate-figure.sh <path-to-puml-file>"
+    exit 1
+fi
+
+if [ ! -f "$1" ]; then
+    echo "ERROR: Input file not found: $1"
+    exit 1
+fi
+
+if ! which docker; then
+    echo "ERROR: Docker must be installed to generate figures!"
+    exit 1
+fi
+
+DIR_NAME=`dirname "$1"`
+FILE_NAME_NO_EXT=`basename "$1" .puml`
+
+cat "$1" | docker run --rm -i think/plantuml -tpng > ${DIR_NAME}/${FILE_NAME_NO_EXT}.png

dev-docs/proposals/0000-proposal-template.md

@@ -0,0 +1,15 @@
+# Proposal #<PR number>: <Proposal Title >
+
+## Overview
+
+## Current shortcomings 
+
+## Benefits of changes
+
+## Affected modules
+
+## Details of the proposal
+
+## Introduced breaking changes
+
+## Proposal work items

package.json

@@ -61,6 +61,13 @@
                 "eachLine": {
                     "prepend": "# "
                 }
+            },
+            "puml": {
+                "prepend": "'",
+                "append": "'",
+                "eachLine": {
+                    "prepend": "' "
+                }
             }
         }
     },