From d3400879a9ad986e17c6fdc7ee07b5e717c286ca Mon Sep 17 00:00:00 2001
From: Boris Parak <parak@cesnet.cz>
Date: Thu, 14 Feb 2019 10:29:05 +0100
Subject: [PATCH] Add Contrib guide and fix cli link

---
 0-quickstart/README.md | 10 +++----
 2-cli/README.md        |  8 ++---
 CONTRIBUTE.md          | 67 ++++++++++++++++++++++++++++++++++++++++++
 SUMMARY.md             |  1 +
 4 files changed, 77 insertions(+), 9 deletions(-)
 create mode 100644 CONTRIBUTE.md

diff --git a/0-quickstart/README.md b/0-quickstart/README.md
index ec6e92f..3d9676f 100644
--- a/0-quickstart/README.md
+++ b/0-quickstart/README.md
@@ -9,7 +9,7 @@ To create a virtual machine instance, you need to
 * start a virtual machine instance,
 * log in to the running instance using *ssh* (secure shell).
 
-## Sign in via the MetaCentrum cloud web interface
+## Sign In
 The web interface is available at [https://cloud.muni.cz](https://cloud.muni.cz).
 
 To sign in,
@@ -19,7 +19,7 @@ To sign in,
 * provide your institution-specific sign-in credentials,
 * wait to be redirected back to our web interface.
 
-## Create an *ssh* key pair
+## Create Key Pair
 All virtual machine instances running in the cloud have to be accessed remotely. The most common way of accessing a virtual machine instance remotely is the secure shell - *ssh*. Using *ssh* requires a pair of cryptographic keys.
 
 1. To create a new *ssh* key pair, go to **Project &gt; Compute &gt; Key Pairs** and click the button "Create Key Pair"
@@ -35,7 +35,7 @@ All virtual machine instances running in the cloud have to be accessed remotely.
   ![](/0-quickstart/CreateKeyPair3.png)
 {% endreveal %}
 
-## Update a security group
+## Update Security Group
 In OpenStack, all incoming traffic from external networks to virtual machine instances is blocked by default. You need to explicitly allow access to individual virtual machine instances and services via a security group.
 
 You need to add two new rules to be able to connect to your new instance (or any instance using the given security group). This is similar to setting up firewall rules on your router or server. If set up correctly, you will be able to access your virtual machine via *ssh* from your local terminal.
@@ -53,7 +53,7 @@ You need to add two new rules to be able to connect to your new instance (or any
   ![](/0-quickstart/SecurityGroups3.png)
 {% endreveal %}
 
-## Start a virtual machine instance
+## Start Instance
 1. Navigate to **Quickstart** and click on "Launch Instance".
 {% reveal text="Show Screenshot" %}
   ![](/0-quickstart/qs1.png)
@@ -87,6 +87,6 @@ You need to add two new rules to be able to connect to your new instance (or any
   ![](/0-quickstart/qs6.png)
 {% endreveal %}
 
-## Log in to the virtual machine instance
+## Log In
 Follow instructions provided by **Quickstart** and log in remotely:
 > ssh -i ${PATH_TO_SSH_KEY_FILE} ${USER}@${IP_ADDRESS}
diff --git a/2-cli/README.md b/2-cli/README.md
index 87221fb..45063dd 100644
--- a/2-cli/README.md
+++ b/2-cli/README.md
@@ -1,10 +1,10 @@
 # Command Line Interface
 
-## Getting API credentials
+## Getting Credentials
 > TODO
 
-## Setting up the environment
+## Setting Up
 > TODO
 
-## Full reference
-See [OpenStack CLI Cheat Sheet](http://docs.openstack.org/user-guide/cli-cheat-sheet.html).
+## Full Reference
+See [OpenStack CLI Documentation](https://docs.openstack.org/python-openstackclient/rocky/).
diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md
new file mode 100644
index 0000000..15ef2ef
--- /dev/null
+++ b/CONTRIBUTE.md
@@ -0,0 +1,67 @@
+# How To Contribute
+Working with our documentation requires the following tools:
+* *git* for version control
+* *nodejs* and *gitbook* for content management
+
+This documentation is written in the *Markdown* markup language.
+
+```bash
+# Debian
+apt-get install nodejs git
+```
+```bash
+# CentOS
+yum install nodejs git
+```
+```bash
+# Fedora
+dnf install nodejs git
+```
+Or see [NodeJS Documentation](https://nodejs.org/en/download/package-manager/) for distro-specific instructions.
+
+## Work-flow Overview
+1. Fork & clone repository
+2. Create a branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Merge Request with the content of your branch
+
+## Fork Repository
+See [GitLab @ ICS MU](https://gitlab.ics.muni.cz/cloud/documentation/forks/new) for details. This will create your own clone of our repository where you will be able to make changes. Once you are happy with your changes, use GitLab to submit them to our original repository.
+
+## Clone Repository
+```bash
+# after creating your own copy of the repository on GitLab
+git clone git@gitlab.ics.muni.cz:${GITLAB_USER}/documentation.git
+```
+
+## Create New Branch
+```bash
+# in `documentation`
+git checkout -b my_change
+```
+
+## Install GitBook
+```bash
+npm install gitbook-cli -g
+
+# in `documentation`
+gitbook install
+```
+This step MAY require `sudo` depending on your system and NodeJS installation method.
+
+## Edit GitBook
+```bash
+# in `documentation`
+gitbook serve
+```
+> Edits will be show live in your browser window, no need to refresh.
+
+## Commit and Push Changes
+```bash
+git commit -am "My updates"
+git push origin my_change
+```
+
+## Submit Changes
+Create a *Merge Request* via [GitLab @ ICS MU](https://gitlab.ics.muni.cz/cloud/documentation/merge_requests/new).
diff --git a/SUMMARY.md b/SUMMARY.md
index ba35d4f..d05f9d8 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -5,4 +5,5 @@
 * [Graphical User Interface](1-gui/README.md)
 * [Command Line Interface](2-cli/README.md)
 * [FAQ](3-faq/README.md)
+* [Contribute](CONTRIBUTE.md)
 * [Glossary](GLOSSARY.md)
-- 
GitLab