From b5d10ddf93afeda54d0ee28c6105172f7d4ac60f Mon Sep 17 00:00:00 2001
From: "Juan Picado @jotadeveloper" <juanpicado19@gmail.com>
Date: Sat, 28 Oct 2017 22:36:18 +0200
Subject: [PATCH] docs: add development documentation, contribution guides,
 etc, wip

---
 wiki/README.md           |  49 ++++++++++------
 wiki/dev/README.md       |  51 +++++++++++++++++
 wiki/dev/build.md        |  70 +++++++++++++++++++++++
 wiki/dev/plugins.md      |   0
 wiki/dev/repositories.md |  28 +++++++++
 wiki/dev/test.md         | 120 +++++++++++++++++++++++++++++++++++++++
 6 files changed, 302 insertions(+), 16 deletions(-)
 create mode 100644 wiki/dev/README.md
 create mode 100644 wiki/dev/build.md
 create mode 100644 wiki/dev/plugins.md
 create mode 100644 wiki/dev/repositories.md
 create mode 100644 wiki/dev/test.md

diff --git a/wiki/README.md b/wiki/README.md
index 178bba856..7c7b9143c 100644
--- a/wiki/README.md
+++ b/wiki/README.md
@@ -2,10 +2,6 @@
 
 `verdaccio` is a fork of **sinopia** and it's backwards compatible.
 
-🚀🚨🚨🚨🚨 **<--- Here we will have a fancy logo soon -->** 🚨🚨🚨🚨🚀
-
-You can vote 👍🏻👍🏻👍🏻 or contribute in [this thread](https://github.com/verdaccio/verdaccio/issues/237).
-
 ## Why should I use verdaccio?👌
 
 
@@ -32,36 +28,57 @@ from a fresh look at the code and the outstanding issues. So here we are 🎉
 
 ## Getting Started
 
+### Installation
+
 * [Installation](install.md)
+
+### Usage
+
 * [Command Line](cli.md)
-* [Understand the configuration file](config.md)
+
+### Configuration
+
+* [The configuration file](config.md)
 * [Setting up *uplinks*](uplinks.md)
 * [Packages Access](packages.md)
+* [Authorization and Access](auth.md)
 * [Enable Notifications](notifications.md)
-* [Authorization and access](auth.md)
-* [Logs](logger.md)
-* [Configure the Web](web.md)
 
-## Advanced Configurations
+* [Custom Logs](logger.md)
 
-* [SSL Certificates](ssl.md)
-* [Installing Plugins](plugins.md)
+### UI Customization
 
-## Servers
+* [Configure the Web](web.md) 
+
+
+## Server Configurations
 
 * [Advanced Server Configuration](server.md)
 * [Reverse Proxy](reverse-proxy.md)
+* [SSL Certificates](ssl.md)
 
-### Windows Configurations
+### Windows Specific Settings
 
 * [Installing As a Windows Service](windows.md)
 * [Installing on IIS server](iis-server.md)
 
+## Extend Verdaccio
+* [Installing Plugins](plugins.md)
+* Create your own plugins
+
 ## DevOps
 
-* [Ansible](ansible.md)
-* [Docker](docker.md)
+* [Configure with Ansible](ansible.md)
+* [Using Docker Image](docker.md)
 
-## Recipes
+## Verdaccio Recipes
 
 * [Learn how to protect your packages](recipes/protect-your-dependencies.md)
+
+## Development
+
+* [I want to to contribute](dev/README.md)
+* [Build verdaccio](dev/build.md)
+* [Create plugins](dev/plugins.md)
+* [Repositories](dev/repositories.md)
+* [Unit Testing](dev/test.md) 
diff --git a/wiki/dev/README.md b/wiki/dev/README.md
new file mode 100644
index 000000000..e815519ae
--- /dev/null
+++ b/wiki/dev/README.md
@@ -0,0 +1,51 @@
+# Contributing
+
+First of all 👏👏 thanks for visiting this page, for us means you are willing to contribute `verdaccio` and we are happy for that. Jumping into a unfamiliar code base is not easy but we are here to help you.
+
+## Comunication Channels
+
+If you are willing for asking we use two channels for discussions:
+
+* [Public Gitter channel](https://gitter.im/verdaccio/)
+* [Contributors Slack channel](https://verdaccio-npm.slack.com) (unfortunately only by email invitation, you might ask in Gitter to be included)
+
+## Firts steps
+
+As a first glance verdaccio is a single repository, but there are many ways you might contribute and variety of techonologies to practice.
+
+### Finding my spot
+
+#### I know or I want to learn Node.js 
+
+Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`. 
+
+#### I would prefer work in the User Interface
+
+Recently we have moved to modern techonologies as `React` and `element-react`.  
+
+#### I feel more confortable improving the stack
+
+Of course we will be happy to help us improving the stack, you can upgrade dependenciesas `eslint`, `stylelint`, `webpack`. Or merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+
+#### I do great Documentation
+
+Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+
+#### I am a Designer
+
+We have a frontend website [http://www.verdaccio.org/](http://www.verdaccio.org/) that will be happy to see your ideas.
+
+#### I am a DevOps
+
+We have a widely popular Docker image [https://hub.docker.com/r/verdaccio/verdaccio/](https://hub.docker.com/r/verdaccio/verdaccio/) that need maintenance and pretty likely huge improvements, we need your knowledge for the benefits of all users.
+
+We have support for **Puppet**, **Ansible** and **Cheff** and we need help in those fields, feel free to see all repositories.
+
+## I'm ready to contribute
+
+If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"*  then I have good nws for you, that's the next step.
+
+You will need learn how to build, [we have prepared a guide just for that](build.md).
+
+Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
+
diff --git a/wiki/dev/build.md b/wiki/dev/build.md
new file mode 100644
index 000000000..81240d06f
--- /dev/null
+++ b/wiki/dev/build.md
@@ -0,0 +1,70 @@
+# Build Verdaccio
+
+Verdaccio relies on `yarn` instead `npm` to download depenedencies.
+
+*Note: the current build only will build with `➜ yarn --version 0.28.4` or minor. It's not compatible with `yarn 1.x`*
+
+```bash
+  yarn install
+```
+
+## Scripts
+
+We have a list of scripts that you will use for diferent kind of tasks, in the following section we describe all posible task based on branches. (yes 🎉🎉🎉 !! 🚧 we are working in the version 3.x that will provide a better and modern stack based on **Babel** and **Flow** 🚧.
+
+
+#### Master branch (2.x)
+
+On master branch the unique part we have to build is the UI which is based on React.js, webpack and CSS Modules.
+
+### Scripts
+
+script | Description 
+--- | --- | 
+release | this script is used to generate changelog and raise up the version according the commits messages
+prepublish | it ensures before publish the new ui is being generated
+test | run all the test 
+pre:ci | specific task for CI, build the UI required for test
+test:ci | run test generating coverage
+test:only | run only test
+test:coverage | run `nyc` as a wrapper to generate coverage with mocha test
+coverage:html | run `nyc` to generate coverage reports
+coverage:publish | publish on `codecov` the coverage (don't use it)
+lint | run the linting for javascript code.
+lint:css | run the linter for `css`
+dev:webui | run a `webpack` server with hot reloading enabled `http://localhost:4872/#/` it requires a `verdaccio` server running in port `4873`.
+pre:webpack | prepare the field for webpack (it a substask of `build:webui`)
+build:webui | create the static assets for the UI with `webpack`
+build:docker | create a local docker image with `verdaccio`
+build:rpi | create a local docker for raspberry pi image with `verdaccio` **(experimental with no support)**
+
+
+#### Branch (3.x)
+
+The next major version is based on `babel` and `flow`. If you switch from master ensure to run `yarn install` again.
+
+*Note: Only new scripts in bold*
+
+### Scripts
+
+script | Description 
+--- | --- | 
+**flow** | run flow check
+**dev:start** | transpile and run `verdaccio` with `babel-node` on hot.
+**code:build** | transpile `verdaccio` with `babel` and  copy transpiled code to `build/`
+release | this script is used to generate changelog and raise up the version according the commits messages
+prepublish | it ensures before publish the new ui is being generated
+test | run all the test 
+pre:ci | specific task for CI, build the UI required for test
+test:ci | run test generating coverage
+test:only | run only test
+test:coverage | run `nyc` as a wrapper to generate coverage with mocha test
+coverage:html | run `nyc` to generate coverage reports
+coverage:publish | publish on `codecov` the coverage (don't use it)
+lint | run the linting for javascript code.
+lint:css | run the linter for `css`
+dev:webui | run a `webpack` server with hot reloading enabled `http://localhost:4872/#/` it requires a `verdaccio` server running in port `4873`.
+pre:webpack | prepare the field for webpack (it a substask of `build:webui`)
+build:webui | create the static assets for the UI with `webpack`
+build:docker | create a local docker image with `verdaccio`
+build:rpi | create a local docker for raspberry pi image with `verdaccio` **(experimental with no support)**
\ No newline at end of file
diff --git a/wiki/dev/plugins.md b/wiki/dev/plugins.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/wiki/dev/repositories.md b/wiki/dev/repositories.md
new file mode 100644
index 000000000..e9cb863f4
--- /dev/null
+++ b/wiki/dev/repositories.md
@@ -0,0 +1,28 @@
+# Repositories
+
+`verdaccio` is composed or multiple repositories you might contribute.
+
+Repository | Usage
+--- | ---| 
+[https://github.com/verdaccio/verdaccio](https://github.com/verdaccio/verdaccio) | The main repository 
+[https://github.com/verdaccio/streams](https://github.com/verdaccio/streams) | Small library to handle streams
+[https://github.com/verdaccio/file-locking](https://github.com/verdaccio/file-locking) | Small library to handle locked files 
+[https://github.com/verdaccio/local-storage](https://github.com/verdaccio/local-storage) | Default dependency for verdaccio to handle local file system storage (since `v3.x`)
+[https://github.com/verdaccio/flow-types](https://github.com/verdaccio/flow-types) | `flow` type definitions for verdaccio and sub dependencies.
+[https://github.com/verdaccio/verdaccio.github.io](https://github.com/verdaccio/verdaccio.github.io) | Public `verdaccio` website and future documentation page. 
+[https://github.com/verdaccio/docker-examples](https://github.com/verdaccio/docker-examples) | Docker examples with `docker-compose` to play around with integrations, (nginx, kubernetes, apache, ldap, etc..)
+[https://github.com/verdaccio/docker-examples](https://github.com/verdaccio/docker-examples) | Docker examples with `docker-compose` to play around with integrations, (nginx, kubernetes, apache, ldap, etc..)
+[https://github.com/verdaccio/puppet-verdaccio](https://github.com/verdaccio/puppet-verdaccio) | Puppet support
+[https://github.com/verdaccio/ansible-verdaccio](https://github.com/verdaccio/ansible-verdaccio) | Ansible support
+[https://github.com/verdaccio/verdaccio-cookbook](https://github.com/verdaccio/verdaccio-cookbook) | Chef support
+
+## Experimental Repos
+
+The following repositories aims to be part of the future infraestructure of `verdaccio` and are just PoC looking for active colaborators.
+
+Repository | Usage
+--- | ---| 
+[https://github.com/verdaccio/verdaccio-plugin-auth-htpasswd](https://github.com/verdaccio/verdaccio-plugin-auth-htpasswd) | Default authentification plugin based on Babel
+[https://github.com/verdaccio/generator-verdaccio-plugin](https://github.com/verdaccio/generator-verdaccio-plugin) | Yeoman generators for future verdaccio plugins
+[https://github.com/verdaccio/blog](https://github.com/verdaccio/blog) | Any article related with verdaccio
+
diff --git a/wiki/dev/test.md b/wiki/dev/test.md
new file mode 100644
index 000000000..5e4961f9b
--- /dev/null
+++ b/wiki/dev/test.md
@@ -0,0 +1,120 @@
+# Unit Test
+
+All tests are split in three folders:
+
+ - `test/unit` - Tests that cover functions that transform data in an non-trivial way. These tests simply `require()` a few files and run code in there, so they are very fast.
+ - `test/functional` - Tests that launch a verdaccio instance and perform a series of requests to it over http. They are slower than unit tests.
+ - `test/integration` - Tests that launch a verdaccio instance and do requests to it using npm. They are really slow and can hit a real npm registry. **This actually has not been tested or 
+
+Unit and functional tests are executed automatically by running `npm test` from the project's root directory. Integration tests are supposed to be executed manually from time to time.
+
+We use `mocha` for all test.
+
+## Script
+
+To run the test script you can use either `npm` or `yarn`. 
+
+```
+yarn run test
+```
+
+That will trigger only two first groups of test, unit and functional.
+
+### Unit Test
+
+The following is just an example how a unit test should looks like. Basically follow the `mocha` standard. Try to describe what exactly does the unit test in a single sentence in the header of the `it` section.
+
+```javacript
+'use strict';
+
+let assert = require('assert');
+let parseInterval = require('../../src/lib/utils').parseInterval;
+
+describe('Parse interval', function() {
+ before(function(done) {
+    ..... some magic stuff before the show
+ });
+
+  it('server should respond on /', function(done) {
+  	... this is an async test
+  });});
+```
+
+### Functional Test
+
+Funtional testing in verdaccio has a bit more of complextity that needs a deep explanation in order to success in your experience.
+
+All starts in the `index.js` file. Let's dive in into it.
+
+```javascript
+// create 3 server instances
+require('./lib/startup');
+...
+
+describe('functional test verdaccio', function() {
+  // recover the server instances
+  const server = process.server;
+  const server2 = process.server2;
+  const server3 = process.server3;
+
+  // On start initialise 3 verdaccio servers
+  before(function(done) {
+    Promise.all([
+      require('./lib/startup').start('./store/test-storage', '/store/config-1.yaml'),
+      require('./lib/startup').start('./store/test-storage2', '/store/config-2.yaml'),
+      require('./lib/startup').start('./store/test-storage3', '/store/config-3.yaml'),
+    ]).then(() => {
+      done();
+    }).catch(function(error) {
+        console.error("error on start servers", error);
+    });
+
+  });
+  
+   before(function() {
+    return Promise.all([server, server2, server3].map(function(server) {
+      // save a lsof -p output in order to compare on finish on finish all test
+    }));
+  });
+
+  ..........
+  // here is the unique line you should add, the new functional test.
+  require('./my-functional-test.js')();
+
+  // On finish kill all server
+  after(function(done) {   
+    Promise.all([check(server), check(server2), check(server3)]).then(function() {
+      done();
+    }, (reason) => {
+      assert.equal(reason, null);
+      done();
+    });
+
+  });
+});
+```
+
+Perhaps this is not he best approach, but, it's how works right now. So, you just learnt how the bootstrap works and how to add a new group of functional tests.
+
+#### The lib/server.js
+
+The server class is just a wrapper that simulates a `npm` client and provides a simple API for the funtional test. 
+
+As we mention in the previous section, we are creating 3 process servers that are accessible in each process as `process.server;`, `process.server2;` and ``process.server3;`.
+
+Using such reference you will be able to send request to any of the 3 instance running.
+
+#### The lib/startup.js
+
+The startup file is the responsable to create the 3 verdaccio instances and inject them to the `process.x` global variable.
+
+#### The lib/request.js
+
+This module holds a `PromiseAssert` which extends from `Promise` adding methods to handle all request from `lib/server.js`.
+
+
+
+
+
+
+