Contributing to the Handbook

This document highlights how to make changes in this project.

For the technical requirements of this project, please check the README.

There was an internal documentation session about contributing to the VSHN Handbook on August 9th, 2019. All the information about it (including link to the video, slides, etc.) is available in the VINT-1429 ticket. Check it out!

Language and Vocabulary

Please follow the following guidelines for your writing:

  • The language of the Handbook is American English.

  • Please use gender-neutral English whenever possible. Refer to people as "they" and "them" instead of "he," "she," "him" or "her."

  • Write short sentences.

  • Introduce enumerated lists (like this one) with a little bit of context (as in the previous paragraph).

  • Beware of common grammar mistakes in written English.

  • Use a spell checker before committing your changes.

The text of the handbook is automatically verified by the vale tool before deployment. You can use the tool locally in your laptop, just using the make check command. As a rule of thumb, your text must not trigger any errors in the output of vale.
When writing content for the Handbook in your own laptop, use the make check command to trigger a verification of your text using the vale tool.

Documents

  • Documents are written in AsciiDoc. Please check the AsciiDoctor user manual for a complete reference of the AsciiDoc language.

  • The pages of the manual are stored in the src/modules/ROOT/pages folder. This is a requirement of the Antora tool used to build the website. The src/modules/ROOT/nav.adoc file contains the navigation bar shown on the left side of the screen.

    • Don’t use subfolders inside the pages folder. Store all pages inside the same level. You can regroup them into sets later on–for example, on the nav.adoc file for the website, or in the handbook.adoc file for dividing the PDF into parts.

  • Filenames should use the underscore character "_" and not the dash "–" to distinguish different parts.

  • Images must be stored in the src/modules/ROOT/assets/images folder, and referenced using the following block macro:

    image::file_name.ext[optional alt text]

Branching Model

We use feature branching with merge requests to support our development workflow:

  • The default branch of the project on GitLab is develop. This branch isn’t deployed to production (published version of the handbook).

  • Changes happen in (short-living) branches. Create such a branch, push changes to it, and open a merge request for review (four-eyes principle) before it gets merged into develop.

  • Every so often, somebody from the Documentation chapter will create an MR to merge develop into master, which automatically triggers a new deployment of the Handbook.

Check the "Delete source branch when merge request is accepted" checkbox when creating new MRs. This will clean up merged branches automatically.

Workflow

In a nutshell, this is how we use Git in this project:

  • To add a new page to the handbook, or to modify or delete an existing one, start a new branch.

  • When done, always create a MR on GitLab, and request a colleague to review and merge the changes.

Everytime you add a new page or delete an existing one, remember to modify the src/modules/ROOT/nav.adoc and the src/handbook.adoc files; the former is the navigation bar shown at the left side of the handbook, the latter is the master file of the PDF & e-book formats.

Tickets & Time Tracking

If your modifications include substantial changes to the contents of the handbook, please create a new task blocking the VINT-1317 project milestone. This new task should summarize in a nutshell the changes that you intend to make. You can then log your time on that specific task.

If you can’t make the changes yourself, assign someone from the Documentation chapter to do them on your behalf.

For smaller changes, simply open a merge request and log your time on the VINT-1321 chore.

Useful Tools

Some recommendations to work with Git:

  1. GitLab Web IDE (integrated, web-based IDE)

  2. Sourcetree (Git GUI for Windows, macOS, Linux)

  3. GitKraken (Git GUI for Windows, macOS, Linux)

  4. Codium (Windows, macOS, Linux) has built-in support

Merge Request Approval Process

MRs are approved by the project editor, or one of their deputies, with prior agreement from the Documentation Chapter. When approved, the changesets of the MR are merged into develop.

Never push commits directly to master. Always create a feature branch and open a MR to merge changes into develop.

Release Process

After merging a MR, its changes are automatically published to APPUiO.

Use Semantic Versioning for version numbers.

Tips for Visual Studio Code Users

Install the Official AsciiDoctor Visual Code extension and then add the following entry to your settings, to allow images to appear in the preview pane and for a better writing experienceg:

"[asciidoc]": {
    "editor.quickSuggestions": {
        "comments": false,
        "other": false,
        "strings": false
    },
    "editor.wordWrap": "wordWrapColumn",
    "editor.wordWrapColumn": 70
},
"asciidoc.preview.attributes": {
    "imagesdir": "../assets/images",
    "experimental": "experimental",
    "toc": "preamble",
    "icons": "font",
    "hide-uri-scheme": "",
    "kroki-server-url": "[KROKI URL HERE]",
    "nofooter": ""
},
"asciidoc.preview.fontFamily": "'Ubuntu',-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'HelveticaNeue-Light', 'Droid Sans', sans-serif",
"asciidoc.use_kroki": true,
"asciidoc.preview.useEditorStyle": false,