Workflow for documentation production in OSM.md

# Workflow for documentation production in OSM

## Introduction

About roles:

- Contributors
- Editor/Reviewer
  - Duties
  - Permissions

The process is based on:

- Text-based edition with Markdown
- Version control with Git, using ETSI's Gitlab respos

## Software requirements

## Contributor

Basic Software:

- Git
- Pandoc
- OpenSSH
- Markdown editor(s). Recommended (both):
  - Integrated: Visual Studio Code
  - WYSIWYG: Typora

### Some recommended extensions for Visual Studio Code

- bat67.markdown-extension-pack
- yzhang.markdown-all-in-one
- DavidAnson.vscode-markdownlint
- satokaz.vscode-markdown-header-coloring
- wayou.vscode-todo-highlight
- streetsidesoftware.code-spell-checker
- bierner.github-markdown-preview
- shd101wyy.markdown-preview-enhanced
- geeklearningio.graphviz-markdown-preview
- eamodio.gitlens
- donjayamanne.githistory
- bierner.markdown-checkbox
- bierner.markdown-emoji
- bierner.markdown-mermaid
- bierner.markdown-preview-github-styles
- bierner.markdown-yaml-preamble
- mrmlnc.vscode-remark
- csholmq.excel-to-markdown-table
- DougFinke.vscode-pandoc
- fcrespo82.markdown-table-formatter
- yzane.markdown-pdf

To install extensions in VSCode you can follow the procedures described in: https://code.visualstudio.com/docs/editor/extension-gallery

## Markdown conversion basics

The basic syntax of Pandoc is rather 

pandoc MyDocument.md -o MyDocument.html

pandoc MyDocument.md -o MyDocument.docx

pandoc MyDocument.md --reference-doc=referenceDocument.docx -o MyDocument.docx


## Git settings

Reference: https://osm.etsi.org/gitlab/osm_doc/test#repo-command-line-instructions

```bash
git config --global user.name "myEOLusername"
git config --global user.email "myusername@mycompany.com"
```

It is also highly advisable adding an SSH key to https://osm.etsi.org/gitlab/profile/keys so that password is not requested in every operation.

## Guide for contributors

### Step 0: Setup the repository in your local environment for the first time

#### If the repository already exists in ETSI's Gitlab but not locally

```bash
git clone git@osm.etsi.org:osm_doc/test.git
```

**TEMPORARY**:

```bash
git clone https://osm.etsi.org/gitlab/osm_doc/test.git
```

#### If the repository already exists in ETSI's Gitlab and the local copy it is not up-to-date

```bash
git pull origin master
```

### Step 1 (**IMPORTANT)**: Create a local branch

This should be based on an up-to-date version of the code in the repo's `master`. If you are unsure, you should do:

```bash
git pull origin master
```

Then create a branch and move to it in order to continue. In this example, we will create a branch called `BranchNewSection` to store a new section that you are working on:

```bash
git checkout -b BranchNewSection
```

### Step 2: Local edition and commits

In this phase, you can edit your files as you would normally do.

From time to time, you might want to "save" snapshots of your changes. This process has two states:

- Putting files with modifications in your _stage area_.
- Once you have all you need in your _stage area_, create a local _commit_ out of this set of changes.

You can add those files to your _stage area_ as needed. For instance, this would add a file called `MyFile.md`:

```bash
git add MyFile.md
```

In case you wanted to add all files with any modification since the last commit, you could do:

```bash
git add .
```

Once you are ready, you can create a commit (which would serve as a kind of local "snapshot" of your changes:

```bash
git commit -m "My message to remember later on what was included in this commit"
```

Then you can continue editing until you are ready to share a contribution.

### Step 3: Contribute your branch and make a merge request

When your are ready, you can push your branch to the remote repo:

```
git push origin BranchNewSection
```

Once you have pushed your branch to the remote repo, you should **inform the editor of it by making a _merge request_**. This can be easily made in the [GitLab web]https://osm.etsi.org/gitlab/osm_doc/test/merge_requests() (your recently pushed branch would be there).

### Step 4: Wait for the result of the review

The merge request might have different potential results:

#### Your contribution was commented by the editor



### Your contribution has been integrated (merged) by the editor

The result would be available in the main edition branch (`master`).

You should update your local repository before attempting further edits:

```
git checkout master
git pull
```


### Step 5: (Once merged) update your local master

## TODO: Guide for editors

### Step 0: Setup of the repository and initial contribution

#### If you start from an empty local folder and the repo in ETSI's Gitlab is still empty **(RECOMMENDED)**



#### If you have the content in a local folder and the repo in ETSI's Gitlab is still empty (initial load of info)

If it was not under Git control yet, initialize it:

```bash
git init
```

Add the URL of the remote repository:

```bash
git remote add origin git@osm.etsi.org:osm_doc/test.git
```