Contributing to the Handbook

This document highlights how to contribute to the project, what belongs in it, and what does not.

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

Purpose of the Handbook

The handbook documents

  • the current state of our organizational structures, practices, vision, mission, values, business overview, processes, guidelines, policies, and how-to guides,

  • or the results of decisions that shape our future organization (in any of the above categories). Things that are planned but not yet the case are marked as such and updated later when they become reality.

It’s for (future) VSHNeers

While it might be likewise interesting for customers and partners to understand VSHN, we write it for VSHNeers and potential future VSHNeers only. Documentation targeting customers, partners or suppliers does not belong here and will be deleted by the maintainers.

The handbook may be referred to in other documents, our website, social media, presentations about how VSHN works and the like, but it must not be part of legally binding documents and contracts with our customers or partners, with one exception: our information security management.

Language and Vocabulary

Please follow these guidelines for your writing:

  • The language of the Handbook is American English.

  • Here, we write for VSHNeers, using easy language but don’t bother whether externals might understand it or not.

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

  • Write short sentences.

  • Try to be on point, writing how things really are or what we agreed on together — marketing fluff and promises don’t belong here.

  • Introduce enumerated lists (like this one) with a 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 on your laptop by 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 on your own laptop, use the make check command to trigger a verification of your text using the vale tool.

Pages

  • The pages of this handbook 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.

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

  • 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 approve or merge the changes.

Every time you add a new page or delete an existing one, remember to modify the src/modules/ROOT/nav.adoc file; this is the navigation bar shown on the left side of the handbook.

Git Commit Messages

Write meaningful Git commit messages so that it’s clear what’s happening in the commit. Maybe you want to rebase your branch before it gets merged into master to have a clean commit history and properly written commit messages.

Merge Request Titles

The GitLab Merge Request title is 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 the title.

The changelog is generated by poopayee.

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 usually approved by a project maintainer, alternatively any other VSHNeer following these contribution guidelines. When approved, the changesets of the MR are merged into master (see Branching Model) and automatically release to the production handbook (see Release Process below).

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

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.

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,

Other Recommended Tools

Recommended Reading