Documentation

As most software projects we also have a lack in documentation. We encourage every VyOS user to help us improve our documentation. This will not only be benefical four you (when reading something up) but also for the whole world.

If you are willing to contribute to our documentation this is the definate guid how to do so.

Note

In contrast to submitting code patches there is no requirement that you open up a Phabricator task prior to submitting a Pull-Request to the documentation.

Forking Workflow

The Forking Workflow is fundamentally different than other popular Git workflows. Instead of using a single server-side repository to act as the “central” codebase, it gives every developer their own server-side repository. This means that each contributor has not one, but two Git repositories: a private local one and a public server-side one.

The main advantage of the Forking Workflow is that contributions can be integrated without the need for everybody to push to a single central repository. Developers push to their own server-side repositories, and only the project maintainer can push to the official repository. This allows the maintainer to accept commits from any developer without giving them write access to the official codebase.

Note

Updates to our documentation should be delivered by a GitHub pull-request. This requires you already have a GitHub account.

  • Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork

  • Clone fork to local machine

  • Change to your new local directory $ cd vyos-documentation

  • Create new branch for your work, use a descriptive name of your work: $ git checkout -b fix-vxlan-typo

  • Make all your changes - please keep our commit rules in mind (Preparding patch/commit). This mainly applies to proper commit messages describing your change (how and why). Please check out the documentation of Sphinx-doc or reStructuredText if you are not familiar with it. This is used for writing our docs.

  • Check your changes by locally building the documentation $ make html. Sphinx will build the html files in the docs/_build folder. We provide you with a Docker container for an easy to use user experience. Check the README.md file of this repository.

  • View modified files by calling $ git status. You will get an overview of all files modified by you. You can add individual files to the Git Index in the next step.

  • Add modified files to Git index $ git add path/to/filename or add all unstaged files $ git add .. All files added to the Git index will be part of you following Git commit.

  • Commit your changes $ git commit -v - your configured editor will now ne launched where you can type in a commit message. Again please make yourself comfortable with out rules (Preparding patch/commit).

  • Push your commits to your GitHub project: $ git push -u origin foo-branch

  • Submit pull-request. In GitHub visit the main repository and you should see a banner suggesting to make a pull request. Fill out the form and describe what you do.

  • Once pull resquests have been approved, you may want to locally update your forked repository too. First you’ll have to add a second remote called upstream which points to our main repository. $ git remote add upstream https://github.com/vyos/vyos-documentation.git

    Check your configured remote repositories:

    $ git remote -v
origin    https://github.com/<username>/vyos-documentation.git (fetch)
origin    https://github.com/<username>/vyos.documentation.git (push)
upstream  https://github.com/vyos/vyos-documentation.git (fetch)
upstream  https://github.com/vyos/vyos-documentation.git (push)

    Your remote repo on Github is called origin, while the original repo you have forked is called upstream. Now you can locally update your forked repo.

    $ git fetch upstream
$ git checkout master
$ git merge upstream/master

  • If you want to update your fork on GitHub, too use the following: $ git push origin master

Style Guide

Sections

We use the following syntax for Headlines.

#####
Parts
#####

********
Chapters
********

Sections
========

Subsections
-----------

Subsubsections
^^^^^^^^^^^^^^

Paragraphs
""""""""""

Address space

Note the following RFCs (RFC 5737, RFC 3849, RFC 5389 and RFC 7042), which describe the reserved public IP addresses and autonomous system numbers for the documentation:

  • 192.0.2.0/24

  • 198.51.100.0/24

  • 203.0.113.0/24

  • 2001:db8::/32

  • 16bit ASN: 64496 - 64511

  • 32bit ASN: 65536 - 65551

  • Unicast MAC Addresses: 00-53-00 to 00-53-FF

  • Multicast MAC-Addresses: 90-10-00 to 90-10-FF

Please don’t use other public address space.

Custom Sphinx-doc Markup

When documenting CLI commands use the .. cfgcmd:: directive for all configuration mode commands. When documenting operational level command use the .. opcmd:: directive. An explanation of the described command should be added below this statement.

Example

.. opcmd:: show protocols static arp

Display all known ARP table entries spanning accross all interfaces

.. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa

This will configure a static ARP entry always resolving `192.0.2.100` to
`00:53:27:de:23:aa`.