Proofread docs in the /contributing directory (#1718)

* Proofread upstream-packages.rst

* Fix line length lint errors

* Initial copyedit for testing.rst

* Proofread build-vyos.rst

* Fix line length errors

* Proofread debugging.rst

* Proofread issues-features.rst

* Complete issuesfeatures.rst proofreading

* Initial proofread development.rst

* Revise proofreading of development.rst

* Remove mentions of Phabricator and Jenkins CI

* Fix line length lint errors

* Fix additional line length lint errors

1 files changed, 302 insertions, 329 deletions

diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst
index 22bebd9c..5de950df 100644
--- a/docs/contributing/development.rst
+++ b/docs/contributing/development.rst
@@ -1,227 +1,210 @@
+:lastproofread: 2025-12-12
+
 .. _development:
 
 ###########
 Development
 ###########
 
-All VyOS source code is hosted on GitHub under the VyOS organization which can
-be found here: https://github.com/vyos
-
-Our code is split into several modules. VyOS is composed of multiple individual
-packages, some of them are forks of upstream packages and are periodically
-synced with upstream, so keeping the whole source under a single repository
-would be very inconvenient and slow. There is now an ongoing effort to
-consolidate all VyOS-specific framework/config packages into vyos-1x package,
-but the basic structure is going to stay the same, just with fewer and fewer
-packages while the base code is rewritten from Perl/BASH into Python using and
-XML based interface definition for the CLI.
-
-The repository that contains all the ISO build scripts is:
-https://github.com/vyos/vyos-build
-
-The README.md file will guide you to use the this top level repository.
+Learn how to contribute to VyOS.
 
-Submit a Patch
-==============
+.. _architecture_overview:
 
-.. warning::
+Architecture overview
+=====================
+VyOS source code is hosted on GitHub in the VyOS organization:
+https://github.com/vyos
 
-  Please read and sign the :doc:`Contributor License Agreement<cla>` before
-  submitting any patches.
+VyOS is composed of multiple modules spread across different
+repositories. Some modules contain forks of upstream
+packages and are periodically synced. 
+VyOS consolidates most packages into the
+`vyos-1x <https://github.com/vyos/vyos-1x>`__
+repository while maintaining a consistent structure. 
+The base code is being rewritten
+from Perl and Bash to Python using an XML-based CLI interface definition.
 
-Patches are always more than welcome. To have a clean and easy to maintain
-repository we have some guidelines when working with Git. A clean repository
-eases the automatic generation of a changelog file.
+VyOS ISO build scripts are hosted in the
+`vyos-build <https://github.com/vyos/vyos-build>`__ repository. See the
+``vyos-build`` repository
+`README.md file <https://github.com/vyos/vyos-build/blob/current/README.md>`__
+for more information on building VyOS ISO images.
 
-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``.
+Contributing code
+=================
 
-.. _prepare_commit:
+.. warning::
 
-Prepare patch/commit
---------------------
+  You must sign the :doc:`Contributor License Agreement<cla>`
+  for your contributions to be accepted.
 
-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
-head. We use a bugtracker known as Phabricator_ for it ("issue tracker" would
-be a better term, but this one stuck).
+VyOS is open-source and welcomes patches.
+All submissions must adhere to these guidelines:
 
-The information is used in three ways:
+* Each commit addresses a single issue or feature.
+* Each commit message references a Phabricator_ task ID
+  (for example, ``T1234``).
+* Each commit is associated with a username and email address
+  to identify the author (see `Configure your Git identity`_).
+* Only submit bugfixes in packages other than https://github.com/vyos/vyos-1x.
+* Commits follow the `coding guidelines`_ outlined below.
 
-* Keep track of the progress (what we've already done in this branch and what
-  we still need to do).
 
-* Prepare release notes for upcoming releases
+Determining package ownership
+-----------------------------
 
-* Help future maintainers of VyOS (it could be you!) to find out why certain
-  things have been changed in the codebase or why certain features have been
-  added
+To determine which VyOS package contains a file you want to modify, use Debian's
+``dpkg -S`` command on your running VyOS installation.
 
-To make this approach work, every change must be associated with a task number
-(prefixed with **T**) and a component. If there is no bug report/feature request
-for the changes you are going to make, you have to create a Phabricator_ task
-first. Once there is an entry in Phabricator_, you should reference its id in
-your commit message, as shown below:
+Submitting your code
+--------------------
 
-* ``ddclient: T1030: auto create runtime directories``
-* ``Jenkins: add current Git commit ID to build description``
+Fork the repository and submit a GitHub pull request. This is the preferred way
+to contribute changes to VyOS.
 
-If there is no Phabricator_ reference in the commits of your pull request, we
-have to ask you to amend the commit message. Otherwise we will have to reject
-it.
+To fork a VyOS repository:
 
-Writing good commit messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+1. Append ``/fork`` to the repository URL on GitHub. For example, to fork
+   ``vyos-1x``, use: https://github.com/vyos/vyos-1x/fork
 
-The format should be and is inspired by: https://git-scm.com/book/ch5-2.html
-It is also worth reading https://chris.beams.io/posts/git-commit/
+2. Clone your fork or add it as a remote to your local repository:
 
-* A single, short, summary of the commit (recommended 50 characters or less,
-  not exceeding 80 characters) containing a prefix of the changed component
-  and the corresponding Phabricator_ reference e.g. ``snmp: T1111:`` or
-  ``ethernet: T2222:`` - multiple components could be concatenated as in
-  ``snmp: ethernet: T3333``
+   - Clone: ``git clone https://github.com/<user>/vyos-1x.git``
+   - Add remote: ``git remote add myfork https://github.com/<user>/vyos-1x.git``
 
-* In some contexts, the first line is treated as the subject of an email and
-  the rest of the text as the body. The blank line separating the summary from
-  the body is critical (unless you omit the body entirely); tools like rebase
-  can get confused if you run the two together.
+.. _Configure your Git identity:
 
-* Followed by a message which describes all the details like:
+3. Configure your Git identity:
 
-  * What/why/how something has been changed, makes everyone's life easier when
-    working with `git bisect`
+   .. code-block:: none
 
-  * 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)
+     git config --global user.name "J. Random Hacker"
+     git config --global user.email "jrhacker@example.net"
 
-  * 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 following exception: ABCDEF``
+4. Make your changes and add files to the Git index:
 
-* Always use the ``-x`` option to the ``git cherry-pick`` command when back or
-  forward porting an individual commit. This automatically appends the line:
-  ``(cherry picked from commit <ID>)`` to the original authors commit message
-  making it easier when bisecting problems.
+   - Single file: ``git add myfile``
+   - Directory: ``git add somedir/*``
 
-* Every change set must be consistent (self containing)! Do not fix multiple
-  bugs in a single commit. If you already worked on multiple fixes in the same
-  file use `git add --patch` to only add the parts related to the one issue
-  into your upcoming commit.
+5. Commit your changes with a meaningful headline and Phabricator_ reference:
 
-Limits:
+   ``git commit``
 
-* We only accept bugfixes in packages other than https://github.com/vyos/vyos-1x
-  as no new functionality should use the old style templates (``node.def`` and
-  Perl/BASH code. Use the new style XML/Python interface instead.
+6. Push to your fork and create a GitHub pull request:
 
-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
+   ``git push``
 
+Alternatively, you can export commits as patches and send them to
+maintainers@vyos.net or attach them directly to the Phabricator_ task:
 
-Determinine source package
---------------------------
+* Export last commit: ``git format-patch``
+* Export last two commits: ``git format-patch -2``
 
-Suppose you want to make a change in a file but yet you do not know
-which of the VyOS packages ship this file. You can determine the VyOS
-package name in question by using Debian's ``dpkg -S`` command of your running
-VyOS installation.
+Commit messages
+===============
 
+For guidance on writing commit messages, review the file history
+with ``git log path/to/file.txt``.
 
-Fork Repository and submit Patch
---------------------------------
+Every change must be associated with a task number (prefixed with **T**) and
+a component. If no bug report or feature request exists for your changes,
+create a Phabricator_ task first. Reference the task ID in your commit message:
 
-Forking the repository and submitting a GitHub pull-request is the preferred
-way of submitting your changes to VyOS. You can fork any VyOS repository to your
-very own GitHub account by just appending ``/fork`` to any repository's URL on
-GitHub. To e.g. fork the ``vyos-1x`` repository, open the following URL in your
-favourite browser: https://github.com/vyos/vyos-1x/fork
+* ``ddclient: T1030: auto create runtime directories``
+* ``Jenkins: add current Git commit ID to build description``
 
-You then can proceed with cloning your fork or add a new remote to your local
-repository:
+If your pull request lacks a Phabricator_ reference, maintainers will request
+that you amend the commit message.
 
-* Clone: ``git clone https://github.com/<user>/vyos-1x.git``
+Writing good commit messages
+-----------------------------
 
-* Fork: ``git remote add myfork https://github.com/<user>/vyos-1x.git``
+Follow the format described in
+the `Git documentation <https://git-scm.com/book/ch5-2.html>`__
+and `Chris Beams' guide <https://chris.beams.io/posts/git-commit/>`__.
 
-In order to record you as the author of the fix please identify yourself to Git
-by setting up your name and email. This can be done local for this one and only
-repository ``git config`` or globally using ``git config --global``.
+Commit message format:
 
-.. code-block:: none
+1. **Summary line** (50 characters recommended, 80 maximum): Include the
+   component
+   prefix and Phabricator_ reference (for example, ``snmp: T1111:`` or
+   ``ethernet: T2222:``). Concatenate multiple components with colons
+   (for example, ``snmp: ethernet: T3333``).
 
-  git config --global user.name "J. Random Hacker"
-  git config --global user.email "jrhacker@example.net"
+2. **Blank line**: Separate the summary from the body. 
+   This blank line is critical.
 
-Make your changes and save them. Do the following for all changes files to
-record them in your created Git commit:
+4. **Message body** with details:
 
-* Add file to Git index using ``git add myfile``, or for a whole directory:
-  ``git add somedir/*``
+   * Describe what changed, why, and how. This helps with ``git bisect``.
+   * Wrap text at 72 characters for readability with ``git log`` on an 80x25
+     terminal.
+   * Reference previous commits when applicable:
+     ``After commit abcd12ef ("snmp: this is a headline")
+     a Python import statement is missing, throwing the following exception:
+     ABCDEF``
 
-* Commit the changes by calling ``git commit``. Please use a meaningful commit
-  headline (read above) and don't forget to reference the Phabricator_ ID.
+5. **Cherry-pick option**: Always use the ``-x`` option when back-porting or
+   forward-porting commits:
 
-* Submit the patch ``git push`` and create the GitHub pull-request.
+   ``git cherry-pick -x <commit>``
 
+   This appends ``(cherry picked from commit <ID>)`` to the commit message,
+   making bisecting easier.
 
-Attach patch to Phorge task
---------------------------------
+6. **Single responsibility**: Each commit must be self-contained. Do not fix
+   multiple bugs in a single commit. Use ``git add --patch`` to stage only
+   the parts related to one issue.
 
-Follow the above steps on how to "Fork repository to submit a Patch". Instead
-of uploading "pushing" your changes to GitHub you can export the patches/
-commits and send it to maintainers@vyos.net or attach it directly to the bug
-(preferred over email)
+Constraints:
 
-* Export last commit to patch file: ``git format-patch`` or export the last two
-  commits into its appropriate patch files: ``git format-patch -2``
+* Bugfixes are only accepted for packages other than
+  https://github.com/vyos/vyos-1x.
+  New functionality must use the new XML/Python interface, not old-style
+  templates (``node.def`` files and Perl/Bash code).
 
-
-Coding Guidelines
+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..
-
+VyOS maintains consistent coding standards to help contributors navigate the
+codebase and understand its logic.
 
 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
+* **Python**: Use 4 spaces per indentation level. Tabs **must not** be used.
+* **XML**: Use 2 spaces per indentation level. Tabs **must not** be used.
+
+Use tools like VIM extensions (xmllint) to enforce correct indentation. Add this
+to your ``.vimrc`` file:
+
+.. code-block:: none
 
-.. 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.
+  au FileType xml setlocal equalprg=xmllint\ --format\ --recover\ -\ 2>/dev/null
 
+Then use ``gg=G`` in command mode to run the linter.
 
 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.
+Use a template processor for generating config files:
 
-The default template processor for VyOS code is Jinja2_.
+* **Jinja2** is the default template processor for VyOS code.
+* Built-in string formatting **may** be used for simple line-oriented formats
+  (for example, iptables rules) where every line is self-contained.
+* Template processors **must** be used for structured, multi-line formats
+  (for example, ISC DHCPd configuration).
 
+Python code
+-----------
 
-Configuration Script Structure and Behaviour
---------------------------------------------
+Configuration scripts and operation mode scripts written in Python3 should
+follow these guidelines:
 
-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 remotely or program using vi(m) this is
-a fair good standard which I hope we can rely on.
+* Wrap lines at 80 characters. This improves readability when browsing
+  GitHub on mobile devices and reads well in side-by-side diffs.
 
-In addition this also helps when browsing the GitHub codebase on a mobile
-device if you happen to be a crazy scientist.
+Structure your scripts with these functions:
 
 .. code-block:: python
 
@@ -280,109 +263,101 @@ device if you happen to be a crazy scientist.
       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.
-
-Other considerations: vyos-configd
-----------------------------------
-
-All scripts now run under the config daemon and must conform to the
-following:
-
-1. The signature and initial four lines of ``get_config(...)`` `must` be as
-   above.
-
-2. Each of ``get_config``, ``verify``, ``apply``, ``generate`` `must`
-   appear, with signatures as above, even if they are a no-op.
-
-3. Instantiations of ``Config`` other than that in ``get_config`` `must not`
-   appear.
-
-4. The legacy function ``my_set`` `must not` appear: modifications of the
-   active config `should not` appear in new code (if absolutely necessary,
-   alternative mechanisms may be used).
-
-XML (used for CLI definitions)
-==============================
-
-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:
+``get_config()``: This function converts a VyOS config object to an abstract
+internal representation. No other function may call the ``vyos.config.Config``
+object directly. Limiting config reads to one function makes it easier to
+modify the config syntax in the future. Additionally, this design improves
+testability since you can construct an internal representation by hand rather
+than mocking the entire config subsystem.
+
+``verify()``: This function validates the internal representation. It must
+raise ``ConfigError`` with a descriptive message if the config is invalid. It
+**must not** make any changes to the system. This design enables future features
+like commit dry-run ("commit test" as in JunOS) where the system can abort a
+commit before making changes.
+
+``generate()``: This function generates config files for system components.
+
+``apply()``: This function applies the generated configuration to the live
+system. Prefer non-disruptive reload when possible. Disruptive operations like
+daemon restarts are acceptable only when:
+
+* The component does not support non-disruptive reload, or
+* The expected service degradation is minimal (for example, auxiliary services
+  like LLDPd)
+
+For high-impact services (VPN daemons, routing protocols), make effort to
+determine if changes can be applied non-disruptively before resorting to
+restarts.
+
+Never modify active configuration directly unless absolutely necessary. Instead,
+generate configuration files and apply them with a single command like service
+reload through systemd. For example, save iptables rules to a file and load them
+with ``iptables-restore`` rather than executing iptables commands one by one.
+
+The ``apply()`` and ``generate()`` functions may raise ``ConfigError`` if the
+daemon fails to start with the updated config. However, this is not a substitute
+for proper config validation in the ``verify()`` function. Make reasonable
+effort to verify that generated configuration is valid and will be accepted by
+the daemon, including cross-checks with other VyOS configuration subtrees when
+necessary.
+
+Exceptions like ``VyOSError`` (raised by ``vyos.config.Config`` on improper
+operations) should not be silenced or caught. While this may produce less
+polished error output for users, it generates better bug reports and helps
+maintainers debug issues.
+
+For reference implementations, see ``ntp.py`` or ``interfaces-bonding.py`` (for
+tag nodes) in the `vyos-1x <https://github.com/vyos/vyos-1x>`__ repository.
+
+Other considerations: ``vyos-configd``
+--------------------------------------
+
+All scripts now run under the config daemon and must conform to these
+requirements:
+
+1. The signature and first four lines of ``get_config(...)`` **must** be as
+   specified above.
+
+2. Each of ``get_config``, ``verify``, ``apply``, and ``generate`` **must**
+   appear
+   with the correct signatures, even if they are a no-op.
+
+3. ``Config`` objects other than those in ``get_config`` **must not** appear.
+
+4. The legacy function ``my_set`` **must not** appear. Modifications to active
+   config **should not** appear in new code (alternative mechanisms may be used
+   if absolutely necessary).
+
+XML for CLI definitions
+=======================
+
+XML interface definitions define the VyOS CLI structure. 
+Before VyOS ``1.2`` (crux), these
+files were created manually. After a redesign, new-style templates are
+automatically generated from XML input files.
+
+VyOS interface definitions come with a RelaxNG schema located in the
+`vyos-1x <https://github.com/vyos/vyos-1x/tree/current/schema>`__
+repository. This schema is a modified version from ``VyConf`` (VyOS ``2.0``).
+VyOS ``1.2.x``
+interface definitions are reusable in future VyOS versions with minimal changes.
+
+Schemas provide two benefits:
+
+* Complete grammar verification
+* Automatic validation against the schema
+
+.. stop_vyoslinter
+The `build-command-templates <https://github.com/vyos/vyos-1x/blob/current/scripts/build-command-templates>`__
+script converts XML definitions to
+old-style templates and verifies them against the schema. A bad definition
+causes the package build to fail. While the XML format is verbose, no other
+format provides this level of verification. Specialized XML editors can help
+manage verbosity.
+.. start_vyoslinter
+
+Example XML interface definition:
 
 .. code-block:: xml
 
@@ -460,35 +435,43 @@ Example:
     </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.
+XML definitions are purely declarative and contain no logic. All logic for
+generating config files, restarting services, and related tasks is implemented
+in configuration scripts.
 
-GNU Preprocessor
-----------------
+Template Processors
+-------------------
 
-XML interface definition files use the `xml.in` file extension which was
-implemented in :vytask:`T1843`. XML interface definitions tend to have a lot of
-duplicated code in areas such as:
+XML interface definition files use the ``.xml.in`` file extension (implemented
+in :vytask:`T1843`). These files use the GCC preprocessor to reduce code
+duplication in common areas:
 
-* VIF (incl. VIF-S/VIF-C)
-* Address
+* VIF (including VIF-S and VIF-C)
+* Address configuration
 * Description
-* Enabled/Disabled
+* Enabled/Disabled state
+
+Instead of repeating XML nodes, use include files with predefined features:
 
-Instead of supplying all those XML nodes multiple times there are now include
-files with predefined features. Brief overview:
+.. stop_vyoslinter
 
-* `IPv4, IPv6 and DHCP(v6)`_ address assignment
-* `IPv4, IPv6`_ address assignment
-* `VLAN (VIF)`_ definition
-* `MAC address`_ assignment
+* `IPv4, IPv6, and DHCP(v6) <https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6-dhcp.xml.i>`__
+  address assignment.
+* `IPv4 and IPv6 <https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/interface/address-ipv4-ipv6.xml.i>`__
+  address assignment.
+* `VLAN (VIF) <https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/accel-ppp/vlan.xml.i>`__
+  definition.
+* `MAC address <https://github.com/vyos/vyos-1x/blob/current/interface-definitions/include/firewall/mac-address.xml.i>`__
+  assignment.
 
-All interface definition XML input files (.in suffix) will be sent to the GCC
-preprocess and the output is stored in the `build/interface-definitions`
-folder. The previously mentioned `scripts/build-command-templates` script
-operates on the `build/interface-definitions` folder to generate all required
-CLI nodes.
+
+The ``.in`` files are preprocessed and stored in the `interface-definitions <https://github.com/vyos/vyos-1x/tree/current/interface-definitions>`__
+folder. The `scripts/build-command-templates <https://github.com/vyos/vyos-1x/blob/current/scripts/build-command-templates>`__
+script then operates on this folder to generate all required CLI nodes.
+
+.. start_vyoslinter
+
+Example preprocessor output:
 
 .. code-block:: none
 
@@ -503,63 +486,57 @@ CLI nodes.
   Generating build/interface-definitions/tftp-server.xml from interface-definitions/tftp-server.xml.in
   [...]
 
+Command Definition Guidelines
+------------------------------
 
-Guidelines
-----------
-
-Use of numbers
-^^^^^^^^^^^^^^^
+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.
+Avoid using numbers in command names unless the number is part of a protocol
+name or similar. For example, ``protocols ospfv3`` is appropriate,
+but ``server-1`` is questionable.
 
-Help String
-^^^^^^^^^^^
+Help Strings
+^^^^^^^^^^^^
 
-To ensure uniform look and feel, and improve readability, we should follow a
-set of guidelines consistently.
+Follow these guidelines for consistent, readable help strings:
 
-Capitalization and punctuation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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.
+* Capitalize the first word of every help string.
+* Do not use 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.
+This standard mirrors network device CLIs and improves aesthetics.
 
 Examples:
 
 * Good: "Frobnication algorithm"
 * Bad: "frobnication algorithm"
 * Bad: "Frobnication algorithm."
-* Horrible: "frobnication algorithm."
+* Incorrect: "frobnication algorithm."
 
-Use of abbreviations and acronyms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Abbreviations and Acronyms
+""""""""""""""""""""""""""
 
-Abbreviations and acronyms **must** be capitalized.
+* Capitalize all abbreviations and acronyms.
 
 Examples:
 
 * Good: "TCP connection timeout"
 * Bad: "tcp connection timeout"
-* Horrible: "Tcp connection timeout"
+* Bad: "Tcp connection timeout"
 
-Acronyms also **must** be capitalized to visually distinguish them from normal
-words:
+* Capitalize acronyms to 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)
+* Good: RADIUS (remote authentication for dial-in user services)
+* Bad: radius (unless referring to circular distance)
 
-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.
+* Follow accepted spelling conventions for mixed-case abbreviations. If it
+  contains "over" or "version", use lowercase. Follow RFC or standard spellings
+  when they exist.
 
 Examples:
 
@@ -567,24 +544,20 @@ Examples:
 * Bad: PPPOE, IPSEC
 * Bad: pppoe, ipsec
 
-Use of verbs
-~~~~~~~~~~~~
+Verbs
+"""""
 
-Verbs **should** be avoided. If a verb can be omitted, omit it.
+* Avoid verbs. 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
-~~~~~~~~~~~~~~~~~~
+* When a verb is essential, use it. For example: "Disable IPv6 forwarding on
+  all interfaces" for ``set system ipv6 disable-forwarding``.
 
-Verbs, when they are necessary, **should** be in their infinitive form.
+* Use infinitive form for necessary verbs.
 
 Examples:
 
@@ -595,20 +568,20 @@ Examples:
 C++ Backend Code
 ================
 
-The CLI parser used in VyOS is a mix of bash, bash-completion helper and the
-C++ backend library [vyatta-cfg](https://github.com/vyos/vyatta-cfg). This
-section is a reference of common CLI commands and the respective entry point
-in the C/C++ code.
+The VyOS CLI parser combines bash, bash-completion helpers, and the C++ backend
+library `vyatta-cfg <https://github.com/vyos/vyatta-cfg>`__. This section
+references common CLI commands and their C/C++ entry points:
 
-* ``set``
+``set``:
 
-  - https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L352
-  - https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L2549
+.. stop_vyoslinter
 
+* https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L352
+* https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/cstore/cstore.cpp#L2549
 
-* ``commit``
+``commit``:
 
-  - https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252
+* https://github.com/vyos/vyatta-cfg/blob/0f42786a0b3/src/commit/commit-algorithm.cpp#L1252
 
 .. include:: /_include/common-references.txt