Workflow for documentation production in OSM.md

# Workflow for documentation production in OSM

## Introduction

The process is based on:

- Text-based edition with Markdown
- Further conversion to multiple formats and templates with Pandoc
- Version control with Git, using ETSI's Gitlab

In the edition process there are two roles:

- **Contributors.** Anyone contributing content to a given document, with no special privileges. They cannot contribute directly to `master` branch, so they have to contribute pushing branches and issuing a _merge request_ (i.e. requesting their intergration).
- **Editor/Reviewer**. The person (or people) in charge of integrating (_merging_) contributions into the main document. In consequence, they can push changes directly to the `master` branch. They should also decide the document split in different files and provide the means to build and convert the document to a given set of target formats and templates.

## Software requirements

## Contributor

Basic Software:

- [Git](https://git-scm.com/)
- [Pandoc](https://pandoc.org/)
- Markdown editor(s). Recommended (both):
  - Integrated: [Visual Studio Code](https://code.visualstudio.com/)
    - The integrated editor supports version control operations graphically, so that usual operations do not require CLI commands necessarily.
  - WYSIWYG: [Typora](https://typora.io/)

### 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 any of the procedures described in: https://code.visualstudio.com/docs/editor/extension-gallery

## Markdown conversion basics

The basic syntax of Pandoc is rather simple. In the simplest cases, it just requires an input file and an output file name, and it will determine the formats based on the extensions.

For instance, this command converts from Markdown to MS-Word format:

```bash
pandoc MyDocument.md -o MyDocument.docx
```

It is also possible to merge several input files into one output file:

```bash
pandoc MyDocument1.md MyDocument2.md -o MyDocument.docx
```

For some target formats, such as HTML, you would need to specify whether you want to produce a fragment (default) or a complete standalone document (using the `-s` switch):

```bash
pandoc -s MyDocument.md -o MyDocument.html
```

In the case of MS-Word target format, a highly useful feature is specifying an existing document (usually based on a specific format template) as reference, so that Pandoc can produce the output document based on the same template:

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

Please note that the reference must be a valid standalone DOC/DOCX document, not an MS-Word template (i.e. DOT/DOTX files are not valid references for Pandoc).

## 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 URL**:

```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
```

#### NOTE: What to do if you committed changes to master by mistake

In case you forgot to create your branch (or moving to it) and made a number of commits directly to your `master` branch by mistake, you will need to use a procedure to move them to a branch, or you will be unable to work with you remote origin.

To achieve it, you can still following some steps to fix your Git history and move the commits to the right place.

Note that **this procedure needs to be followed exactly as it is described** or might lead to unintended loss of commits. In particular, you should understand that:

- You are **rewriting** your Git history and, therefore, might delete wrong entries if you make any mistake. Please read these steps carefully and follow them accurately.
- Any changes not committed before starting this procedure. If they are relevant for your, you should commit them (to `master`) as well.

As said, you can follow this procedure (assuming that you start in your `master` branch):

```bash
git branch newbranch              # Create a new branch, saving the desired commits
git reset --hard origin/master    # Move master back to the latest commit common to the remote
git checkout newbranch            # Go to the new branch that still has the desired commits
```

### 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, in the _Merge Requests_ area (on the left side bar). Your recently pushed branch would be there to be selected for your new merge request.

### Step 4: Result of the review

Following your _merge request_, the editor will revise the changes suggested in your branch and decide whether they should be merged or receive comments from the editor.

If your contribution was **commented** by the editor, you should try to address the comments in your branch and push them again if appropriate (in case the contribution has not been entirely rejected by the editor).

If your contribution was integrated (**merged**) by the editor, the result will be available in the main edition branch (i.e. `master`) as a new commit . Therefore, you should update your local repository (`pull`) before attempting further edits:

```bash
git checkout master
git pull origin 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
```