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 of the project.

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.

    • 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.

  • Navigation on the left side of the screen in browser has to be configured in src/modules/ROOT/nav.adoc.

  • Files must be in src/handbook.adoc for PDF creation.

  • 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]
  • You can use :keywords: to generate a <meta name="keywords" content="…​"> tag which search engines might pick up, they aren’t relevant for our handbook search.

Branching Model

  • The default branch of the project on GitLab is master. This branch is deployed to production.

  • Changes happen in (short-living) branches, starting from the master branch. Create such a branch, push changes to it, and open a merge request for review (four-eyes principle) before it gets merged into master. This can create a preview deployment under $branchname.preview.handbook.vshn.ch, once you hit the "Deploy" button. After the branch has been merged, the preview deployment gets removed again.

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 an MR on GitLab, and request a colleague to review and merge the changes.

Every time 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 on the left side of the handbook, the latter is the master file of the PDF & e-book formats.

Git Commit Messages

The Git commit messages are used in the Changelog. Please write the messages accordingly. If you don’t want your change to be in the changelog (for example typo fixing) you can add [nochangelog] to your commit message. Maybe you want to rebase your branch before it gets merged into master to have a clean commit history and properly written commit messages.

Only the first line (summary) is included in the Changelog. If you want to tell a bit more about the change, add a blank line and then write as much as you want / need.

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 Interest Group to do them on your behalf.

For smaller changes, simply open a merge request.

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 Interest Group. When approved, the changesets of the MR are merged into master (see Branching Model).

Make sure your MR has the MR Template in its merge request description.

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

Release Process

After merging an MR to the master branch:

  • A changelog gets generated from the Git commit messages (by Poopayee).

    • Add [nochangelog] to your commit message if you don’t want it to be in the changelog.

  • Changes are automatically published to the production deployment on APPUiO Cloud.

There is no need for a Git tag.

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,