contribution: restructure entire chapter

- move subchapters to sub-sub chapters and try to have more internal
  references to e.g. commit rules.

8 files changed, 711 insertions, 735 deletions

diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst
index 29b7f71a..2c490e44 100644
--- a/docs/contributing/build-vyos.rst
+++ b/docs/contributing/build-vyos.rst
@@ -38,8 +38,8 @@ To be able to use Docker_, the current non-root user should be added to the
    on SMB or NFS shares will result in the container failing to build properly!
 
 
-Generating the container
-------------------------
+Build Docker Container
+----------------------
 
 The container can built by hand or by fetching the pre-built one from DockerHub.
 Using the pre-built VyOS DockerHub organisation (https://hub.docker.com/u/vyos)
@@ -61,8 +61,8 @@ The container can always be built directly from source:
    container in ``crux`` and ``current`` can and will differ once VyOS makes
    the move towards Debian (10) Buster.
 
-Build ISO inside container
---------------------------
+Build ISO
+---------
 
 After the container is generated either manually or fetched from DockerHub,
 a fresh build of the VyOS ISO can begin.
@@ -120,4 +120,171 @@ Good luck!
    or ``rolling`` image. Make sure to choose the matching container for the
    version of VyOS that is being built.
 
+
+
+.. _upstream_packages:
+
+Upstream packages
+-----------------
+
+Many base system packages are pulled straight from Debian's main and contrib
+repositories, but there are exceptions.
+
+This chapter lists those exceptions and gives you a brief overview what we
+have done on those packages. If you only wan't to build yourself a fresh ISO
+you can completely skip this chapter. It may become interesting once you have
+a VyOS deep dive.
+
+vyos-netplug
+^^^^^^^^^^^^
+
+Due to issues in the upstream version that sometimes set interfaces down, a
+modified version is used.
+
+The source is located at https://github.com/vyos/vyos-netplug
+
+In the future, we may switch to using systemd infrastructure instead. Building
+it doesn't require a special procedure.
+
+keepalived
+^^^^^^^^^^
+
+Keepalived normally isn't updated to newer feature releases between Debian
+versions, so we are building it from source.
+
+Debian does keep their package in git, but it's upstream tarball imported into
+git without its original commit history. To be able to merge new tags in, we
+keep a fork of the upstream repository with packaging files imported from
+Debian at http://github.com/vyos/keepalived-upstream
+
+strongswan
+^^^^^^^^^^
+
+Our StrongSWAN build differs from the upstream:
+
+- strongswan-nm package build is disabled since we don't use NetworkManager
+- Patches for DMVPN are merged in
+
+The source is at https://github.com/vyos/vyos-strongswan
+
+DMVPN patches are added by this commit:
+https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226
+
+Our op mode scripts use the python-vici module, which is not included in
+Debian's build, and isn't quite easy to integrate in that build. For this
+reason we debianize that module by hand now, using this procedure:
+
+0. Install https://pypi.org/project/stdeb/
+1. `cd vyos-strongswan`
+2. `./configure --enable-python-eggs`
+3. `cd src/libcharon/plugins/vici/python`
+4. `make`
+5. `python3 setup.py --command-packages=stdeb.command bdist_deb`
+
+The package ends up in deb_dist dir.
+
+ppp
+^^^
+
+Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and
+non-informative pppX requires a patch that is neither in the upstream nor in
+Debian.
+
+We keep a fork of Debian's repo at https://github.com/vyos/ppp-debian
+
+The patches for pre-up renaming are:
+
+* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae
+* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9
+
+Additionally, there's a patch for reopening the log file to better support
+logging to files, even though it's less essential:
+https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055f
+
+The patches were written by Stephen Hemminger back in the Vyatta times.
+
+mdns-repeater
+^^^^^^^^^^^^^
+
+This package doesn't exist in Debian. A debianized fork is kept at
+https://github.com/vyos/mdns-repeater
+
+No special build procedure is required.
+
+udp-broadcast-relay
+^^^^^^^^^^^^^^^^^^^
+
+This package doesn't exist in Debian. A debianized fork is kept at
+https://github.com/vyos/udp-broadcast-relay
+
+No special build procedure is required.
+
+Linux kernel
+^^^^^^^^^^^^
+
+In the past a fork of the Kernel source code was kept at the well-known
+location of https://github.com/vyos/vyos-kernel - where it is kept for history.
+
+Nowadays the Kernel we use is the upstream source code which is patched
+with two additional patches from the good old Vyatta times which never made it
+into the mainstream Kernel. The patches can be found here:
+https://github.com/vyos/vyos-build-kernel/tree/current/patches/kernel and are
+automatically applied to the Kernel by the Jenkins Pipeline which is used to
+generate the Kernel binaries.
+
+The Pipeline script not only builds the Kernel with the configuration named
+``x86_64_vyos_defconfig`` which is located in the vyos-build-kernel repository,
+too - but in addition also builds some Intel out-of-tree drivers, WireGuard
+(as long it is not upstreamed) and Accel-PPP.
+
+The ``Jenkinsfile`` tries to be as verbose as possible on each individual build
+step.
+
+Linux Firmware
+^^^^^^^^^^^^^^
+
+More and more hardware cards require an additional firmware which is not open
+source. The Kernel community hosts a special linux-firmware Git repository
+with all available binary files which can be loaded by the Kernel.
+
+The ``vyos-build`` repository fetches a specific commit of the linux-firmware
+repository and embeds those binaries into the resulting ISO image. This step is
+done in the ``data/live-build-config/hooks/live/40-linux-firmware.chroot`` file.
+
+If the firmware needs to be updated it is sufficient to just exchange the Git
+commit id we reference in our build.
+
+Intel NIC drivers
+^^^^^^^^^^^^^^^^^
+
+We do not make use of the building Intel NIC drivers except for e1000e. Main
+reason is that the out of tree Intel drivers seem be perform a bit better,
+e.q. have proper receive-side-scaling and multi-queue support.
+
+Drivers are build as part of the Kernel Pipeline - read above.
+
+Accel-PPP
+^^^^^^^^^
+
+Accel-PPP used to be an upstream fork for quiet some time but now has been
+converted to make use of the upstream source code and build system.
+
+It is build as part of the Kernel Pipeline - read above.
+
+hvinfo
+^^^^^^
+
+A fork with packaging changes for VyOS is kept at https://github.com/vyos/hvinfo
+
+The original repo is at https://github.com/dmbaturin/hvinfo
+
+It's an Ada program and requires GNAT and gprbuild for building, dependencies
+are properly specified so just follow debuild's suggestions.
+
+Per-file modifications
+^^^^^^^^^^^^^^^^^^^^^^
+
+vyos-replace package replaces the upstream dhclient-script with a modified
+version that is aware of the VyOS config.
+
 .. _Docker: https://www.docker.com
diff --git a/docs/contributing/coding_guidelines.rst b/docs/contributing/coding_guidelines.rst
deleted file mode 100644
index 634c3e61..00000000
--- a/docs/contributing/coding_guidelines.rst
+++ /dev/null
@@ -1,198 +0,0 @@
-.. _coding_guidelines:
-
-Python Coding Guidelines
-========================
-
-The switch to the Python programming language for new code is not merely a
-change of the language, but a chance to rethink and improve the programming
-approach.
-
-Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS
-config, generating daemon configs, and restarting processes is all mixed up.
-
-Python (or any other language, for that matter) does not provide automatic
-protection from bad design, so we need to also devise design guidelines and
-follow them to keep the system extensible and maintainable.
-
-But we are here to assist you and want to guide you through how you can become
-a good VyOS contributor. The rules we have are not there to punish you - the
-rules are in place to help us all. What does it mean? By having a consistent
-coding style it becomes very easy for new contributors and also longtime
-contributors to navigate through the sources and all the implied logic of
-the spaghetti code.
-
-Please use the following template as good starting point when developing new
-modules or even rewrite a whole bunch of code in the new style XML/Pyhon
-interface.
-
-Configuration script structure and behaviour
---------------------------------------------
-
-Your configuration script or operation mode script which is also written in
-Python3 should have a line break on 80 characters. This seems to be a bit odd
-nowadays but as some people also work remotly or programm using vi(m) this is
-a fair good standard which I hope we can rely on.
-
-In addition this also helps when browsing the GitHub codebase on a mobile
-device if you happen to be a crazy scientist.
-
-.. code-block:: python
-
-  #!/usr/bin/env python3
-  #
-  # Copyright (C) 2019 VyOS maintainers and contributors
-  #
-  # This program is free software; you can redistribute it and/or modify
-  # it under the terms of the GNU General Public License version 2 or later as
-  # published by the Free Software Foundation.
-  #
-  # This program is distributed in the hope that it will be useful,
-  # but WITHOUT ANY WARRANTY; without even the implied warranty of
-  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-  # GNU General Public License for more details.
-  #
-  # You should have received a copy of the GNU General Public License
-  # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-  import sys
-
-  from vyos.config import Config
-  from vyos.util import ConfigError
-
-  def get_config():
-      vc = Config()
-      # Convert the VyOS config to an abstract internal representation
-      config = ...
-      return config
-
-  def verify(config):
-      # Verify that configuration is valid
-      if invalid:
-          raise ConfigError("Descriptive message")
-      return True
-
-  def generate(config):
-      # Generate daemon configs
-      pass
-
-  def apply(config):
-      # Apply the generated configs to the live system
-      pass
-
-  try:
-      config = get_config()
-      verify(config)
-  except ConfigError as e:
-      print(e)
-      sys.exit(1)
-
-The ``get_config()`` function must convert the VyOS config to an abstract,
-internal representation. No other function is allowed to call the ``vyos.config.
-Config`` object method directly. The rationale for it is that when config reads
-are mixed with other logic, it's very hard to change the config syntax since
-you need to weed out every occurrence of the old syntax. If syntax-specific
-code is confined to a single function, the rest of the code can be left
-untouched as long as the internal representation remains compatible.
-
-Another advantage is testability of the code. Mocking the entire config
-subsystem is hard, while constructing an internal representation by hand is
-way simpler.
-
-The ``verify()`` function takes your internal representation of the config and
-checks if it's valid, otherwise it must raise ``ConfigError`` with an error
-message that describes the problem and possibly suggests how to fix it. It must
-not make any changes to the system. The rationale for it is again testability
-and, in the future when the config backend is ready and every script is
-rewritten in this fashion, ability to execute commit dry run ("commit test"
-like in JunOS) and abort commit before making any changes to the system if an
-error is found in any component.
-
-The ``generate()`` function generates config files for system components.
-
-The ``apply()`` function applies the generated configuration to the live
-system. It should use non-disruptive reload whenever possible. It may execute
-disruptive operations such as daemon process restart if a particular component
-does not support non-disruptive reload, or when the expected service degradation
-is minimal (for example, in case of auxiliary services such as LLDPd). In case
-of high impact services such as VPN daemon and routing protocols, when non-
-disruptive reload is supported for some but not all types of configuration
-changes, scripts authors should make effort to determine if a configuration
-change can be done in a non-disruptive way and only resort to disruptive restart
-if it cannot be avoided.
-
-Unless absolutely necessary, configuration scripts should not modify the active
-configuration of system components directly. Whenever at all possible, scripts
-should generate a configuration file or files that can be applied with a single
-command such as reloading a service through systemd init. Inserting statements
-one by one is particularly discouraged, for example, when configuring netfilter
-rules, saving them to a file and loading it with iptables-restore should always
-be preferred to executing iptables directly.
-
-The ``apply()`` and ``generate()`` functions may ``raise ConfigError`` if, for
-example, the daemon failed to start with the updated config. It shouldn't be a
-substitute for proper config checking in the ``verify()`` function. All
-reasonable effort should be made to verify that generated configuration is
-valid and will be accepted by the daemon, including, when necessary, cross-
-checks with other VyOS configuration subtrees.
-
-Exceptions, including ``VyOSError`` (which is raised by ``vyos.config.Config``
-on improper config operations, such as trying to use ``list_nodes()`` on a
-non-tag node) should not be silenced or caught and re-raised as config error.
-Sure this will not look pretty on user's screen, but it will make way better
-bug reports, and help users (and most VyOS users are IT professionals) do their
-own debugging as well.
-
-For easy orientation we suggest you take a look on the ``ntp.py`` or
-``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be
-found in the vyos-1x_ repository.
-
-
-Coding guidelines
------------------
-
-Like any other project we have some small guidelines about our source code, too.
-The rules we have are not there to punish you - the rules are in place to help
-us all. By having a consistent coding style it becomes very easy for new
-and also longtime contributors to navigate through the sources and all the
-implied logic of any one source file..
-
-Language
-********
-
-Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No
-considerations for Python 2 compatibility **should** be taken at any time.
-
-Formatting
-**********
-
-* Python: Tabs **shall not** be used. Every indentation level should be 4 spaces
-* XML: Tabs **shall not** be used. Every indentation level should be 2 spaces
-
-.. note: There are extensions to e.g. VIM (xmllint) which will help you to get
-   your indention levels correct. Add to following to your .vimrc file:
-   ``au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\
-   2>/dev/null`` now you can call the linter using ``gg=G`` in command mode.
-
-Text generation
-***************
-
-Template processor **should** be used for generating config files. Built-in
-string formatting **may** be used for simple line-oriented formats where every
-line is self-contained, such as iptables rules. Template processor **must** be
-used for structured, multi-line formats such as those used by ISC DHCPd.
-
-The default template processor for VyOS code is jinja2.
-
-Code policy
------------
-
-When modifying the source code, remember these rules of the legacy elimination
-campaign:
-
-* No new features in Perl
-* No old style command definitions
-* No code incompatible with Python3
-
-.. _process: https://blog.vyos.io/vyos-development-digest-10
-.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/
-.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata
diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index 3ac9cf6f..61c45dba 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -20,7 +20,6 @@ https://github.com/vyos/vyos-build
 
 The README.md file will guide you to use the this top level repository.
 
-
 Submit a patch
 --------------
 
@@ -31,9 +30,10 @@ eases the automatic generation of a changelog file.
 A good approach for writing commit messages is actually to have a look at the
 file(s) history by invoking ``git log path/to/file.txt``.
 
+.. _prepare_commit:
 
-Preparding patch/commit
-^^^^^^^^^^^^^^^^^^^^^^^
+Preparing patch/commit
+^^^^^^^^^^^^^^^^^^^^^^
 
 In a big system, such as VyOS, that is comprised of multiple components, it's
 impossible to keep track of all the changes and bugs/feature requests in one's
@@ -81,12 +81,12 @@ post: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 
   * All text of the commit message should be wrapped at 72 characters if
     possible which makes reading commit logs easier with ``git log`` on a
-	standard terminal (which happens to be 80x25)
+    standard terminal (which happens to be 80x25)
 
   * If applicable a reference to a previous commit should be made linking
     those commits nicely when browsing the history: ``After commit abcd12ef
-	("snmp: this is a headline") a Python import statement is missing,
-	throwing the follwoing exception: ABCDEF``
+    ("snmp: this is a headline") a Python import statement is missing,
+    throwing the follwoing exception: ABCDEF``
 
 * Always use the ``-x`` option to the ``git cherry-pick`` command when back or
   forward porting an individual commit. This automatically appends the line:
@@ -107,7 +107,6 @@ Limits:
 Please submit your patches using the well-known GitHub pull-request against our
 repositories found in the VyOS GitHub organisation at https://github.com/vyos
 
-
 Determining package for a fix
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -125,7 +124,6 @@ This means the file in question (``/opt/vyatta/sbin/vyatta-update-webproxy.pl``)
 is located in the ``vyatta-webproxy`` package which can be found here:
 https://github.com/vyos/vyatta-webproxy
 
-
 Fork repository to submit a Patch
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -162,7 +160,6 @@ record them in your created Git commit:
 
 * Submit the patch ``git push`` and create the GitHub pull-request.
 
-
 Attach patch to Phabricator task
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -174,4 +171,454 @@ commits and send it to maintainers@vyos.net or attach it directly to the bug
 * Export last commit to patch file: ``git format-patch`` or export the last two
   commits into its appropriate patch files: ``git format-patch -2``
 
+Coding Guidelines
+-----------------
+
+Like any other project we have some small guidelines about our source code, too.
+The rules we have are not there to punish you - the rules are in place to help
+us all. By having a consistent coding style it becomes very easy for new
+and also longtime contributors to navigate through the sources and all the
+implied logic of any one source file..
+
+Python 3 **shall** be used. How long can we keep Python 2 alive anyway? No
+considerations for Python 2 compatibility **should** be taken at any time.
+
+Formatting
+^^^^^^^^^^
+
+* Python: Tabs **shall not** be used. Every indentation level should be 4 spaces
+* XML: Tabs **shall not** be used. Every indentation level should be 2 spaces
+
+.. note: There are extensions to e.g. VIM (xmllint) which will help you to get
+   your indention levels correct. Add to following to your .vimrc file:
+   ``au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\
+   2>/dev/null`` now you can call the linter using ``gg=G`` in command mode.
+
+Text generation
+###############
+
+Template processor **should** be used for generating config files. Built-in
+string formatting **may** be used for simple line-oriented formats where every
+line is self-contained, such as iptables rules. Template processor **must** be
+used for structured, multi-line formats such as those used by ISC DHCPd.
+
+The default template processor for VyOS code is Jinja2_.
+
+Summary
+#######
+
+When modifying the source code, remember these rules of the legacy elimination
+campaign:
+
+* No new features in Perl
+* No old style command definitions
+* No code incompatible with Python3
+
+Python
+------
+
+The switch to the Python programming language for new code is not merely a
+change of the language, but a chance to rethink and improve the programming
+approach.
+
+Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS
+config, generating daemon configs, and restarting processes is all mixed up.
+
+Python (or any other language, for that matter) does not provide automatic
+protection from bad design, so we need to also devise design guidelines and
+follow them to keep the system extensible and maintainable.
+
+But we are here to assist you and want to guide you through how you can become
+a good VyOS contributor. The rules we have are not there to punish you - the
+rules are in place to help us all. What does it mean? By having a consistent
+coding style it becomes very easy for new contributors and also longtime
+contributors to navigate through the sources and all the implied logic of
+the spaghetti code.
+
+Please use the following template as good starting point when developing new
+modules or even rewrite a whole bunch of code in the new style XML/Pyhon
+interface.
+
+Configuration script structure and behaviour
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Your configuration script or operation mode script which is also written in
+Python3 should have a line break on 80 characters. This seems to be a bit odd
+nowadays but as some people also work remotly or programm using vi(m) this is
+a fair good standard which I hope we can rely on.
+
+In addition this also helps when browsing the GitHub codebase on a mobile
+device if you happen to be a crazy scientist.
+
+.. code-block:: python
+
+  #!/usr/bin/env python3
+  #
+  # Copyright (C) 2019 VyOS maintainers and contributors
+  #
+  # This program is free software; you can redistribute it and/or modify
+  # it under the terms of the GNU General Public License version 2 or later as
+  # published by the Free Software Foundation.
+  #
+  # This program is distributed in the hope that it will be useful,
+  # but WITHOUT ANY WARRANTY; without even the implied warranty of
+  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+  # GNU General Public License for more details.
+  #
+  # You should have received a copy of the GNU General Public License
+  # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  import sys
+
+  from vyos.config import Config
+  from vyos.util import ConfigError
+
+  def get_config():
+      vc = Config()
+      # Convert the VyOS config to an abstract internal representation
+      config = ...
+      return config
+
+  def verify(config):
+      # Verify that configuration is valid
+      if invalid:
+          raise ConfigError("Descriptive message")
+      return True
+
+  def generate(config):
+      # Generate daemon configs
+      pass
+
+  def apply(config):
+      # Apply the generated configs to the live system
+      pass
+
+  try:
+      config = get_config()
+      verify(config)
+  except ConfigError as e:
+      print(e)
+      sys.exit(1)
+
+The ``get_config()`` function must convert the VyOS config to an abstract,
+internal representation. No other function is allowed to call the ``vyos.config.
+Config`` object method directly. The rationale for it is that when config reads
+are mixed with other logic, it's very hard to change the config syntax since
+you need to weed out every occurrence of the old syntax. If syntax-specific
+code is confined to a single function, the rest of the code can be left
+untouched as long as the internal representation remains compatible.
+
+Another advantage is testability of the code. Mocking the entire config
+subsystem is hard, while constructing an internal representation by hand is
+way simpler.
+
+The ``verify()`` function takes your internal representation of the config and
+checks if it's valid, otherwise it must raise ``ConfigError`` with an error
+message that describes the problem and possibly suggests how to fix it. It must
+not make any changes to the system. The rationale for it is again testability
+and, in the future when the config backend is ready and every script is
+rewritten in this fashion, ability to execute commit dry run ("commit test"
+like in JunOS) and abort commit before making any changes to the system if an
+error is found in any component.
+
+The ``generate()`` function generates config files for system components.
+
+The ``apply()`` function applies the generated configuration to the live
+system. It should use non-disruptive reload whenever possible. It may execute
+disruptive operations such as daemon process restart if a particular component
+does not support non-disruptive reload, or when the expected service degradation
+is minimal (for example, in case of auxiliary services such as LLDPd). In case
+of high impact services such as VPN daemon and routing protocols, when non-
+disruptive reload is supported for some but not all types of configuration
+changes, scripts authors should make effort to determine if a configuration
+change can be done in a non-disruptive way and only resort to disruptive restart
+if it cannot be avoided.
+
+Unless absolutely necessary, configuration scripts should not modify the active
+configuration of system components directly. Whenever at all possible, scripts
+should generate a configuration file or files that can be applied with a single
+command such as reloading a service through systemd init. Inserting statements
+one by one is particularly discouraged, for example, when configuring netfilter
+rules, saving them to a file and loading it with iptables-restore should always
+be preferred to executing iptables directly.
+
+The ``apply()`` and ``generate()`` functions may ``raise ConfigError`` if, for
+example, the daemon failed to start with the updated config. It shouldn't be a
+substitute for proper config checking in the ``verify()`` function. All
+reasonable effort should be made to verify that generated configuration is
+valid and will be accepted by the daemon, including, when necessary, cross-
+checks with other VyOS configuration subtrees.
+
+Exceptions, including ``VyOSError`` (which is raised by ``vyos.config.Config``
+on improper config operations, such as trying to use ``list_nodes()`` on a
+non-tag node) should not be silenced or caught and re-raised as config error.
+Sure this will not look pretty on user's screen, but it will make way better
+bug reports, and help users (and most VyOS users are IT professionals) do their
+own debugging as well.
+
+For easy orientation we suggest you take a look on the ``ntp.py`` or
+``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be
+found in the vyos-1x_ repository.
+
+XML - CLI
+---------
+
+The bash (or better vbash) completion in VyOS is defined in *templates*.
+Templates are text files (called ``node.def``) stored in a directory tree. The
+directory names define the command names, and template files define the command
+behaviour. Before VyOS 1.2 (crux) this files were created by hand. After a
+complex redesign process_ the new style template are automatically generated
+from a XML input file.
+
+XML interface definitions for VyOS come with a RelaxNG schema and are located
+in the vyos-1x_ module. This schema is a slightly modified schema from VyConf_
+alias VyOS 2.0 So VyOS 1.2.x interface definitions will be reusable in Nextgen
+VyOS Versions with very minimal changes.
+
+The great thing about schemas is not only that people can know the complete
+grammar for certain, but also that it can be automatically verified. The
+`scripts/build-command-templates` script that converts the XML definitions to
+old style templates also verifies them against the schema, so a bad definition
+will cause the package build to fail. I do agree that the format is verbose, but
+there is no other format now that would allow this. Besides, a specialized XML
+editor can alleviate the issue with verbosity.
+
+Example:
+^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <!-- Cron configuration -->
+  <interfaceDefinition>
+    <node name="system">
+      <children>
+        <node name="task-scheduler">
+          <properties>
+            <help>Task scheduler settings</help>
+          </properties>
+          <children>
+            <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py">
+              <properties>
+                <help>Scheduled task</help>
+                <valueHelp>
+                  <format>&lt;string&gt;</format>
+                  <description>Task name</description>
+                </valueHelp>
+                <priority>999</priority>
+              </properties>
+              <children>
+                <leafNode name="crontab-spec">
+                  <properties>
+                    <help>UNIX crontab time specification string</help>
+                  </properties>
+                </leafNode>
+                <leafNode name="interval">
+                  <properties>
+                    <help>Execution interval</help>
+                    <valueHelp>
+                      <format>&lt;minutes&gt;</format>
+                      <description>Execution interval in minutes</description>
+                    </valueHelp>
+                    <valueHelp>
+                      <format>&lt;minutes&gt;m</format>
+                      <description>Execution interval in minutes</description>
+                    </valueHelp>
+                    <valueHelp>
+                      <format>&lt;hours&gt;h</format>
+                      <description>Execution interval in hours</description>
+                    </valueHelp>
+                    <valueHelp>
+                      <format>&lt;days&gt;d</format>
+                      <description>Execution interval in days</description>
+                    </valueHelp>
+                    <constraint>
+                      <regex>[1-9]([0-9]*)([mhd]{0,1})</regex>
+                    </constraint>
+                  </properties>
+                </leafNode>
+                <node name="executable">
+                  <properties>
+                    <help>Executable path and arguments</help>
+                  </properties>
+                  <children>
+                    <leafNode name="path">
+                      <properties>
+                        <help>Path to executable</help>
+                      </properties>
+                    </leafNode>
+                    <leafNode name="arguments">
+                      <properties>
+                        <help>Arguments passed to the executable</help>
+                      </properties>
+                    </leafNode>
+                  </children>
+                </node>
+              </children>
+            </tagNode>
+          </children>
+        </node>
+      </children>
+    </node>
+  </interfaceDefinition>
+
+Command definitions are purely declarative, and cannot contain any logic. All
+logic for generating config files for target applications, restarting services
+and so on is implemented in configuration scripts instead.
+
+Guidelines
+^^^^^^^^^^
+
+Use of numbers
+##############
+
+Use of numbers in command names **should** be avoided unless a number is a
+part of a protocol name or similar. Thus, ``protocols ospfv3`` is perfectly
+fine, but something like ``server-1`` is questionable at best.
+
+Help String
+###########
+
+To ensure uniform look and feel, and improve readability, we should follow a
+set of guidelines consistently.
+
+Capitalization and punctuation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first word of every help string **must** be capitalized. There **must not**
+be a period at the end of help strings.
+
+Rationale: this seems to be the unwritten standard in network device CLIs, and
+a good aesthetic compromise.
+
+Examples:
+
+* Good: "Frobnication algorithm"
+* Bad: "frobnication algorithm"
+* Bad: "Frobnication algorithm."
+* Horrible: "frobnication algorithm."
+
+Use of abbreviations and acronyms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Abbreviations and acronyms **must** be capitalized.
+
+Examples:
+
+* Good: "TCP connection timeout"
+* Bad: "tcp connection timeout"
+* Horrible: "Tcp connectin timeout"
+
+Acronyms also **must** be capitalized to visually distinguish them from normal
+words:
+
+Examples:
+
+* Good: RADIUS (as in remote authentication for dial-in user services)
+* Bad: radius (unless it's about the distance between a center of a circle and
+  any of its points)
+
+Some abbreviations are traditionally written in mixed case. Generally, if it
+contains words "over" or "version", the letter **should** be lowercase. If
+there's an accepted spelling (especially if defined by an RFC or another
+standard), it **must** be followed.
+
+Examples:
+
+* Good: PPPoE, IPsec
+* Bad: PPPOE, IPSEC
+* Bad: pppoe, ipsec
+
+Use of verbs
+~~~~~~~~~~~~
+
+Verbs **should** be avoided. If a verb can be omitted, omit it.
+
+Examples:
+
+* Good: "TCP connection timeout"
+* Bad: "Set TCP connection timeout"
+
+If a verb is essential, keep it. For example, in the help text of ``set system
+ipv6 disable-forwarding``, "Disable IPv6 forwarding on all interfaces" is a
+perfectly justified wording.
+
+Prefer infinitives
+~~~~~~~~~~~~~~~~~~
+
+Verbs, when they are necessary, **should** be in their infinitive form.
+
+Examples:
+
+* Good: "Disable IPv6 forwarding"
+* Bad: "Disables IPv6 forwarding"
+
+Migrating old CLI
+^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Old concept/syntax
+     - New syntax
+     - Notes
+   * - mynode/node.def
+     - <node name="mynode"> </node>
+     - Leaf nodes (nodes with values) use <leafNode> tag instead
+   * - mynode/node.tag , tag:
+     - <tagNode name="mynode> </node>
+     -
+   * - help: My node
+     - <properties> <help>My node</help>
+     -
+   * - val_help: <format>; some string
+     - <properties> <valueHelp> <format> format </format> <description> some
+       string </description>
+     - Do not add angle brackets around the format, they will be inserted
+       automatically
+   * - syntax:expression: pattern
+     - <properties> <constraint> <regex> ...
+     - <constraintErrorMessage> will be displayed on failure
+   * - syntax:expression: $VAR(@) in "foo", "bar", "baz"
+     - None
+     - Use regex
+   * - syntax:expression: exec ...
+     - <properties> <constraint> <validator> <name ="foo" argument="bar">
+     - "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed,
+       <constraintErrorMessage> will be displayed on failure
+   * - syntax:expression: (arithmetic expression)
+     - None
+     - External arithmetic validator may be added if there's demand, complex
+       validation is better left to commit-time scripts
+   * - priority: 999
+     - <properties> <priority>999</priority>
+     - Please leave a comment explaining why the priority was chosen (e.g. "after
+       interfaces are configured")
+   * - multi:
+     - <properties> <multi/>
+     - Only applicable to leaf nodes
+   * - allowed: echo foo bar
+     - <properties> <completionHelp> <list> foo bar </list>
+     -
+   * - allowed: cli-shell-api listNodes vpn ipsec esp-group
+     - <properties> <completionHelp> <path> vpn ipsec esp-group </path> ...
+     -
+   * - allowed: /path/to/script
+     - <properties> <completionHelp> <script> /path/to/script </script> ...
+     -
+   * - default:
+     - None
+     - Move default values to scripts
+   * - commit:expression:
+     - None
+     - All commit time checks should be in the verify() function of the script
+   * - begin:/create:/delete:
+     - None
+     - All logic should be in the scripts
+
+.. _process: https://blog.vyos.io/vyos-development-digest-10
+.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata
+.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/
+.. _Jinja2: https://jinja.palletsprojects.com/
 .. _Phabricator: https://phabricator.vyos.net
\ No newline at end of file
diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst
index 96fc167c..b5f9bf2d 100644
--- a/docs/contributing/documentation.rst
+++ b/docs/contributing/documentation.rst
@@ -10,6 +10,10 @@ 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.
+
 Guide
 -----
 
@@ -17,102 +21,81 @@ Updates to our documentation should be delivered by a GitHub pull-request. In
 order to create a pull-request you need to fork our documentation code first.
 This requires you already have a GitHub account.
 
-1. Fork the project on GitHub https://github.com/vyos/vyos-documentation/fork
-2. Clone your fork to your local machine
-    ```shell
-    $ git clone https://github.com/YOUR_USERNAME/vyos-documentation
-    ```
-3. Change to your new local directory vyos-documentation
-4. Create a new branch for your work. You can use a name that describes what
-   you do
-   ```shell
-   $ git checkout -b fix-vxlan-typo
-   ```
-5. Make all your changes - please keep out commit rules in mind. This mainly
-   applies to a proper commit message describing your change. Please check the
-   documentation if you aren't familiar with `sphinx-doc <https://www.sphinx-doc.org>`_ or
-   `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-
-   Note the following RFCs, which describe the reserved public IP addresses and
-   autonomous system numbers for the documentation: RFC5737_, RFC3849_,
-   RFC5389_ and RFC7042_:
-
-   * 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.
-
-6. Check your changes by locally building the documentation
-    ```shell
-    $ cd docs; make html
-    ```
-
-    Sphinx will build the html files in the ``docs/_build`` folder
-
-7. Add modified files to Git index
-    ```shell
-    $ git add path/to/filname
-    ```
-    or add all unstaged files
-    ```shell
-    $ git add .
-    ````
-
-8. Commit your changes
-    ```shell
-    $ git commit -m "rename vxlan set syntax"
-    ```
-
-9. Push your commits to your GitHub project:
-    ```shell
-    $ git push -u origin fix-vxlan-typo
-    ```
-
-10. 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.
-
-11. Once pull resquests have been approved, you may want to locally update your
-    forked repository too. First you'll have to add the remote upstream
-    repository.
-
-	```shell
-	$ git remote add upstream https://github.com/vyos/vyos-documentation.git
-	```
-
-    Check your configured remote repositories.
-	```shell
-	$ git remote -v
-	origin    https://github.com/YOUR_USERNAME/vyos-documentation.git (fetch)
-	origin    https://github.com/YOUR_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.
-	```shell
-	$ git fetch upstream
-	$ git checkout master
-	$ git merge upstream/master
-	```
-
-    If you want to update your fork on GitHub, too use the following:
-
-	```shell
-	$ git push origin master
-	```
+* Fork the project on GitHub https://github.com/vyos/vyos-documentation/fork
+
+* Clone fork to local machine
+
+* Change to your new local directory 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 out commit rules in mind
+  (:ref:`prepare_commit`). This mainly applies to a proper commit message
+  describing your change. Please check the documentation if you aren't familiar
+  with Sphinx-doc_ or reStructuredText_.
+
+  Note the following RFCs (RFC5737_, RFC3849_, RFC5389_ and RFC7042_), 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.
+
+* Check your changes by locally building the documentation ``$ make html``
+  Sphinx will build the html files in the ``docs/_build`` folder
+
+* Add modified files to Git index ``$ git add path/to/filname`` or add all
+  unstaged files ``$ git add .``
+
+* Commit your changes ``$ git commit -m "vxlan: rework CLI syntax"``
+
+* Push your commits to your GitHub project: ``$ git push -u origin
+  fix-vxlan-typo``
+
+* 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 the remote upstream
+  repository. ``$ git remote add upstream
+  https://github.com/vyos/vyos-documentation.git``
+
+  Check your configured remote repositories:
+
+  .. code-block:: sh
+
+    $ git remote -v
+    origin    https://github.com/YOUR_USERNAME/vyos-documentation.git (fetch)
+    origin    https://github.com/YOUR_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.
+
+  .. code-block:: sh
+
+    $ 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``
 
 .. _RFC5737: https://tools.ietf.org/html/rfc5737
 .. _RFC3849: https://tools.ietf.org/html/rfc3849
 .. _RFC5389: https://tools.ietf.org/html/rfc5398
-.. _RFC7042: https://tools.ietf.org/html/rfc7042
-
+.. _RFC7042: https://tools.ietf.org/html/
+.. _Sphinx-doc: https://www.sphinx-doc.org
+.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _Phabricator: https://phabricator.vyos.net
diff --git a/docs/contributing/issues_features.rst b/docs/contributing/issues-features.rst
index 02de2df6..fd6225b9 100644
--- a/docs/contributing/issues_features.rst
+++ b/docs/contributing/issues-features.rst
@@ -1,10 +1,10 @@
 .. _issues_features:
 
-Issues and Feature requests
-===========================
+Issues/Feature requests
+=======================
 
-Bug Report / Issue
-------------------
+Bug Report/Issue
+----------------
 Issues or bugs are found in any software project. VyOS is not an exception.
 
 All issues should be reported to the developers. This lets the developers know
@@ -51,7 +51,7 @@ Report a Bug
 
 Create an account on VyOS Phabricator_. Phabricator_ is located at
 https://phabricator.vyos.net. To create a bug-report use the quick link in the
-left side under the specific project. 
+left side under the specific project.
 
 * Provide as much information as you can
 * Which version of VyOS are you using? ``run show version``
diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst
deleted file mode 100644
index 8ae3150f..00000000
--- a/docs/contributing/upstream-packages.rst
+++ /dev/null
@@ -1,155 +0,0 @@
-.. _upstream_packages:
-
-Upstream packages
-=================
-
-Many base system packages are pulled straight from Debian's main and contrib
-repositories, but there are exceptions.
-
-vyos-netplug
-------------
-
-Due to issues in the upstream version that sometimes set interfaces down, a
-modified version is used.
-
-The source is located at https://github.com/vyos/vyos-netplug
-
-In the future, we may switch to using systemd infrastructure instead. Building
-it doesn't require a special procedure.
-
-keepalived
-----------
-
-Keepalived normally isn't updated to newer feature releases between Debian
-versions, so we are building it from source.
-
-Debian does keep their package in git, but it's upstream tarball imported into
-git without its original commit history. To be able to merge new tags in, we
-keep a fork of the upstream repository with packaging files imported from
-Debian at http://github.com/vyos/keepalived-upstream
-
-strongswan
-----------
-
-Our StrongSWAN build differs from the upstream:
-
-- strongswan-nm package build is disabled since we don't use NetworkManager
-- Patches for DMVPN are merged in
-
-The source is at https://github.com/vyos/vyos-strongswan
-
-DMVPN patches are added by this commit:
-https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226
-
-Our op mode scripts use the python-vici module, which is not included in
-Debian's build, and isn't quite easy to integrate in that build. For this
-reason we debianize that module by hand now, using this procedure:
-
-0. Install https://pypi.org/project/stdeb/
-1. `cd vyos-strongswan`
-2. `./configure --enable-python-eggs`
-3. `cd src/libcharon/plugins/vici/python`
-4. `make`
-5. `python3 setup.py --command-packages=stdeb.command bdist_deb`
-
-The package ends up in deb_dist dir.
-
-ppp
----
-
-Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and
-non-informative pppX requires a patch that is neither in the upstream nor in
-Debian.
-
-We keep a fork of Debian's repo at https://github.com/vyos/ppp-debian
-
-The patches for pre-up renaming are:
-
-* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae
-* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9
-
-Additionally, there's a patch for reopening the log file to better support
-logging to files, even though it's less essential:
-https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055f
-
-The patches were written by Stephen Hemminger back in the Vyatta times.
-
-mdns-repeater
--------------
-
-This package doesn't exist in Debian. A debianized fork is kept at
-https://github.com/vyos/mdns-repeater
-
-No special build procedure is required.
-
-udp-broadcast-relay
--------------------
-
-This package doesn't exist in Debian. A debianized fork is kept at
-https://github.com/vyos/udp-broadcast-relay
-
-No special build procedure is required.
-
-Linux kernel
-------------
-
-In the past a fork of the Kernel source code was kept at the well-known
-location of https://github.com/vyos/vyos-kernel - where it is kept for history.
-
-Nowadays the Kernel we use is the upstream source code which is patched
-with two additional patches from the good old Vyatta times which never made it
-into the mainstream Kernel. The patches can be found here:
-https://github.com/vyos/vyos-build-kernel/tree/current/patches/kernel and are
-automatically applied to the Kernel by the Jenkins Pipeline which is used to
-generate the Kernel binaries.
-
-The Pipeline script not only builds the Kernel with the configuration named
-``x86_64_vyos_defconfig`` which is located in the vyos-build-kernel repository,
-too - but in addition also builds some Intel out-of-tree drivers, WireGuard
-(as long it is not upstreamed) and Accel-PPP.
-
-The ``Jenkinsfile`` tries to be as verbose as possible on each individual build
-step.
-
-Linux firmware
---------------
-
-More and more hardware cards require an additional firmware which is not open
-source. The Kernel community hosts a special linux-firmware Git repository
-with all available binary files which can be loaded by the Kernel.
-
-The ``vyos-build`` repository fetches a specific commit of the linux-firmware
-repository and embeds those binaries into the resulting ISO image. This step is
-done in the ``data/live-build-config/hooks/live/40-linux-firmware.chroot`` file.
-
-If the firmware needs to be updated it is sufficient to just exchange the Git
-commit id we reference in our build.
-
-Intel drivers
--------------
-
-Are build as part of the Kernel Pipeline - read above.
-
-Accel-PPP
----------
-
-Accel-PPP used to be an upstream fork for quiet some time but now has been
-converted to make use of the upstream source code and build system.
-
-It is build as part of the Kernel Pipeline - read above.
-
-hvinfo
-------
-
-A fork with packaging changes for VyOS is kept at https://github.com/vyos/hvinfo
-
-The original repo is at https://github.com/dmbaturin/hvinfo
-
-It's an Ada program and requires GNAT and gprbuild for building, dependencies
-are properly specified so just follow debuild's suggestions.
-
-Per-file modifications
-------------------------
-
-vyos-replace package replaces the upstream dhclient-script with a modified
-version that is aware of the VyOS config.
diff --git a/docs/contributing/vyos_cli.rst b/docs/contributing/vyos_cli.rst
deleted file mode 100644
index 322b0be6..00000000
--- a/docs/contributing/vyos_cli.rst
+++ /dev/null
@@ -1,265 +0,0 @@
-.. _vyos_cli:
-
-The VyOS CLI
-============
-
-The bash (or better vbash) completion in VyOS is defined in *templates*.
-Templates are text files (called ``node.def``) stored in a directory tree. The
-directory names define the command names, and template files define the command
-behaviour. Before VyOS 1.2 (crux) this files were created by hand. After a
-complex redesign process_ the new style template are automatically generated
-from a XML input file.
-
-XML interface definitions for VyOS come with a RelaxNG schema and are located
-in the vyos-1x_ module. This schema is a slightly modified schema from VyConf_
-alias VyOS 2.0 So VyOS 1.2.x interface definitions will be reusable in Nextgen
-VyOS Versions with very minimal changes.
-
-The great thing about schemas is not only that people can know the complete
-grammar for certain, but also that it can be automatically verified. The
-`scripts/build-command-templates` script that converts the XML definitions to
-old style templates also verifies them against the schema, so a bad definition
-will cause the package build to fail. I do agree that the format is verbose, but
-there is no other format now that would allow this. Besides, a specialized XML
-editor can alleviate the issue with verbosity.
-
-Example XML File
-----------------
-
-.. code-block:: xml
-
-  <?xml version="1.0"?>
-  <!-- Cron configuration -->
-  <interfaceDefinition>
-    <node name="system">
-      <children>
-        <node name="task-scheduler">
-          <properties>
-            <help>Task scheduler settings</help>
-          </properties>
-          <children>
-            <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py">
-              <properties>
-                <help>Scheduled task</help>
-                <valueHelp>
-                  <format>&lt;string&gt;</format>
-                  <description>Task name</description>
-                </valueHelp>
-                <priority>999</priority>
-              </properties>
-              <children>
-                <leafNode name="crontab-spec">
-                  <properties>
-                    <help>UNIX crontab time specification string</help>
-                  </properties>
-                </leafNode>
-                <leafNode name="interval">
-                  <properties>
-                    <help>Execution interval</help>
-                    <valueHelp>
-                      <format>&lt;minutes&gt;</format>
-                      <description>Execution interval in minutes</description>
-                    </valueHelp>
-                    <valueHelp>
-                      <format>&lt;minutes&gt;m</format>
-                      <description>Execution interval in minutes</description>
-                    </valueHelp>
-                    <valueHelp>
-                      <format>&lt;hours&gt;h</format>
-                      <description>Execution interval in hours</description>
-                    </valueHelp>
-                    <valueHelp>
-                      <format>&lt;days&gt;d</format>
-                      <description>Execution interval in days</description>
-                    </valueHelp>
-                    <constraint>
-                      <regex>[1-9]([0-9]*)([mhd]{0,1})</regex>
-                    </constraint>
-                  </properties>
-                </leafNode>
-                <node name="executable">
-                  <properties>
-                    <help>Executable path and arguments</help>
-                  </properties>
-                  <children>
-                    <leafNode name="path">
-                      <properties>
-                        <help>Path to executable</help>
-                      </properties>
-                    </leafNode>
-                    <leafNode name="arguments">
-                      <properties>
-                        <help>Arguments passed to the executable</help>
-                      </properties>
-                    </leafNode>
-                  </children>
-                </node>
-              </children>
-            </tagNode>
-          </children>
-        </node>
-      </children>
-    </node>
-  </interfaceDefinition>
-
-Configuration mode command definitions
---------------------------------------
-
-Command definitions are purely declarative, and cannot contain any logic. All
-logic for generating config files for target applications, restarting services
-and so on is implemented in configuration scripts instead.
-
-Command syntax guidelines
-*************************
-
-Use of numbers
-^^^^^^^^^^^^^^
-
-Use of numbers in command names **should** be avoided unless a number is a
-part of a protocol name or similar. Thus, ``protocols ospfv3`` is perfectly
-fine, but something like ``server-1`` is questionable at best.
-
-Help string guidelines
-**********************
-
-To ensure uniform look and feel, and improve readability, we should follow a
-set of guidelines consistently.
-
-Capitalization and punctuation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The first word of every help string **must** be capitalized. There **must not**
-be a period at the end of help strings.
-
-Rationale: this seems to be the unwritten standard in network device CLIs, and
-a good aesthetic compromise.
-
-Examples:
-
-* Good: "Frobnication algorithm"
-* Bad: "frobnication algorithm"
-* Bad: "Frobnication algorithm."
-* Horrible: "frobnication algorithm."
-
-Use of abbreviations and acronyms
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Abbreviations and acronyms **must** be capitalized.
-
-Examples:
-
-* Good: "TCP connection timeout"
-* Bad: "tcp connection timeout"
-* Horrible: "Tcp connectin timeout"
-
-Acronyms also **must** be capitalized to visually distinguish them from normal
-words:
-
-Examples:
-
-* Good: RADIUS (as in remote authentication for dial-in user services)
-* Bad: radius (unless it's about the distance between a center of a circle and
-  any of its points)
-
-Some abbreviations are traditionally written in mixed case. Generally, if it
-contains words "over" or "version", the letter **should** be lowercase. If
-there's an accepted spelling (especially if defined by an RFC or another
-standard), it **must** be followed.
-
-Examples:
-
-* Good: PPPoE, IPsec
-* Bad: PPPOE, IPSEC
-* Bad: pppoe, ipsec
-
-Use of verbs
-^^^^^^^^^^^^
-
-Verbs **should** be avoided. If a verb can be omitted, omit it.
-
-Examples:
-
-* Good: "TCP connection timeout"
-* Bad: "Set TCP connection timeout"
-
-If a verb is essential, keep it. For example, in the help text of ``set system
-ipv6 disable-forwarding`, "Disable IPv6 forwarding on all interfaces" is a
-perfectly justified wording.
-
-Prefer infinitives
-^^^^^^^^^^^^^^^^^^
-
-Verbs, when they are necessary, **should** be in their infinitive form.
-
-Examples:
-
-* Good: "Disable IPv6 forwarding"
-* Bad: "Disables IPv6 forwarding"
-
-Mapping old node.def style to new XML definitions
--------------------------------------------------
-
-.. list-table::
-   :widths: 25 25 50
-   :header-rows: 1
-
-   * - Old concept/syntax
-     - New syntax
-     - Notes
-   * - mynode/node.def
-     - <node name="mynode"> </node>
-     - Leaf nodes (nodes with values) use <leafNode> tag instead
-   * - mynode/node.tag , tag:
-     - <tagNode name="mynode> </node>
-     -
-   * - help: My node
-     - <properties> <help>My node</help>
-     -
-   * - val_help: <format>; some string
-     - <properties> <valueHelp> <format> format </format> <description> some
-       string </description>
-     - Do not add angle brackets around the format, they will be inserted
-       automatically
-   * - syntax:expression: pattern
-     - <properties> <constraint> <regex> ...
-     - <constraintErrorMessage> will be displayed on failure
-   * - syntax:expression: $VAR(@) in "foo", "bar", "baz"
-     - None
-     - Use regex
-   * - syntax:expression: exec ...
-     - <properties> <constraint> <validator> <name ="foo" argument="bar">
-     - "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed,
-       <constraintErrorMessage> will be displayed on failure
-   * - syntax:expression: (arithmetic expression)
-     - None
-     - External arithmetic validator may be added if there's demand, complex
-       validation is better left to commit-time scripts
-   * - priority: 999
-     - <properties> <priority>999</priority>
-     - Please leave a comment explaining why the priority was chosen (e.g. "after
-       interfaces are configured")
-   * - multi:
-     - <properties> <multi/>
-     - Only applicable to leaf nodes
-   * - allowed: echo foo bar
-     - <properties> <completionHelp> <list> foo bar </list>
-     -
-   * - allowed: cli-shell-api listNodes vpn ipsec esp-group
-     - <properties> <completionHelp> <path> vpn ipsec esp-group </path> ...
-     -
-   * - allowed: /path/to/script
-     - <properties> <completionHelp> <script> /path/to/script </script> ...
-     -
-   * - default:
-     - None
-     - Move default values to scripts
-   * - commit:expression:
-     - None
-     - All commit time checks should be in the verify() function of the script
-   * - begin:/create:/delete:
-     - None
-     - All logic should be in the scripts
-
-.. _process: https://blog.vyos.io/vyos-development-digest-10
-.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/
-.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata
diff --git a/docs/index.rst b/docs/index.rst
index 8230ffac..5ac20b8f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -81,12 +81,9 @@ Contributing
    :maxdepth: 2
 
    contributing/build-vyos
-   contributing/issues_features
+   contributing/issues-features
    contributing/development
-   contributing/vyos_cli
-   contributing/coding_guidelines
    contributing/documentation
-   contributing/upstream-packages
 
 ################
 Copyright Notice