feat: flip swap mechanism — MD as primary, RST as override (Phase 1)

This is the first of three phases inverting the per-page swap mechanism
so MD becomes the canonical primary and RST becomes the rare override.

Phase 1 — file renames + conf.py exclude_patterns flip only:
- Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix)
  for all 254 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.rst (add rst- prefix)
  for the same 254 stems
- Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty
  comment-only since no pages need the RST fallback right now
- conf.py exclude_patterns flipped: rst-*.rst is now excluded by default
  instead of md-*.md
- conf.py runtime-artifact references updated to _rst_override_state.json
  and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce
  these names; for now no swap script runs because overrides list is empty)

Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py
with inverted rename direction, delete scripts/import_myst.py + tests, and
update tests/test_swap_sources.py for the new semantics.

Phase 3 will be the cleanup pass and ready-for-review flip.

Generated by robots https://vyos.io

1 files changed, 197 insertions, 0 deletions

diff --git a/docs/contributing/rst-testing.rst b/docs/contributing/rst-testing.rst
new file mode 100644
index 00000000..d7455103
--- /dev/null
+++ b/docs/contributing/rst-testing.rst
@@ -0,0 +1,197 @@
+:lastproofread: 2025-12-02
+
+.. _testing:
+
+#######
+Testing
+#######
+
+One of the major features introduced in VyOS 1.3 is an automated test
+framework. When you assemble an ISO image, several things can go wrong.
+VyOS uses this framework to detect issues before they cause downstream problems.
+
+This section describes how the automated testing process at VyOS works.
+
+Smoketests
+==========
+
+Smoketests execute predefined VyOS CLI commands and check if the desired
+daemon or service configuration is rendered.
+
+When an ISO image is assembled by the `VyOS CI`_, the ``BUILD_SMOKETEST``
+parameter is enabled by default. This extends the ISO configuration line
+with the following packages:
+
+.. code-block:: python
+
+  def CUSTOM_PACKAGES = ''
+    if (params.BUILD_SMOKETESTS)
+      CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest'
+
+If you plan to build your own custom ISO image and want to use VyOS's
+smoketests, ensure that you have the `vyos-1x-smoketest` package installed.
+
+The ``make test`` command from the vyos-build_ repository launches a new
+QEMU instance, and the ISO image is first installed to the virtual hard disk.
+
+After the first boot into the newly installed system, the main Smoketest script
+is executed. It can be found at `/usr/bin/vyos-smoketest`.
+
+The script searches for executable test cases under
+``/usr/libexec/vyos/tests/smoke/cli/`` and executes them one by one.
+
+.. note:: Smoketests will alter the system configuration. If you are logged
+  in remotely, you may lose your connection to the system.
+
+.. note:: To enable smoketest debugging (print the CLI set commands used),
+  run: ``touch /tmp/vyos.smoketest.debug``.
+
+Manual Smoketest Run
+--------------------
+
+Each test is contained in its own file, so you can execute a single Smoketest
+manually by running the Python test script.
+
+Example:
+
+.. code-block:: none
+
+  vyos@vyos:~$ /usr/libexec/vyos/tests/smoke/cli/test_protocols_bgp.py
+  test_bgp_01_simple (__main__.TestProtocolsBGP) ... ok
+  test_bgp_02_neighbors (__main__.TestProtocolsBGP) ... ok
+  test_bgp_03_peer_groups (__main__.TestProtocolsBGP) ... ok
+  test_bgp_04_afi_ipv4 (__main__.TestProtocolsBGP) ... ok
+  test_bgp_05_afi_ipv6 (__main__.TestProtocolsBGP) ... ok
+  test_bgp_06_listen_range (__main__.TestProtocolsBGP) ... ok
+  test_bgp_07_l2vpn_evpn (__main__.TestProtocolsBGP) ... ok
+  test_bgp_08_zebra_route_map (__main__.TestProtocolsBGP) ... ok
+  test_bgp_09_distance_and_flowspec (__main__.TestProtocolsBGP) ... ok
+  test_bgp_10_vrf_simple (__main__.TestProtocolsBGP) ... ok
+  test_bgp_11_confederation (__main__.TestProtocolsBGP) ... ok
+  test_bgp_12_v6_link_local (__main__.TestProtocolsBGP) ... ok
+  test_bgp_13_solo (__main__.TestProtocolsBGP) ... ok
+
+  ----------------------------------------------------------------------
+  Ran 13 tests in 348.191s
+
+  OK
+
+Interface-based tests
+---------------------
+
+Our smoketests not only test daemons and services, but also check if interface
+configuration works as expected. There is a common base class named
+``base_interfaces_test.py`` that holds all the common code for interface tests.
+
+These common tests consist of:
+
+* Add one or more IP addresses
+* DHCP client and DHCPv6 prefix delegation
+* MTU size
+* IP and IPv6 options
+* Port description
+* Port disable
+* VLANs (QinQ and regular 802.1q)
+* ...
+
+.. note:: When you are working on interface configuration and want to test
+  if the Smoketests pass, you would normally lose the remote SSH connection
+  to your :abbr:`DUT (Device Under Test)`. To handle this, some interface-based
+  tests can be called with an environment variable beforehand to limit the
+  number of interfaces used in the test. By default, all interfaces (e.g., all
+  Ethernet interfaces) are used.
+
+.. code-block:: none
+
+  vyos@vyos:~$ TEST_ETH="eth1 eth2" /usr/libexec/vyos/tests/smoke/cli/test_interfaces_bonding.py
+  test_add_multiple_ip_addresses (__main__.BondingInterfaceTest) ... ok
+  test_add_single_ip_address (__main__.BondingInterfaceTest) ... ok
+  test_bonding_hash_policy (__main__.BondingInterfaceTest) ... ok
+  test_bonding_lacp_rate (__main__.BondingInterfaceTest) ... ok
+  test_bonding_min_links (__main__.BondingInterfaceTest) ... ok
+  test_bonding_remove_member (__main__.BondingInterfaceTest) ... ok
+  test_dhcpv6_client_options (__main__.BondingInterfaceTest) ... ok
+  test_dhcpv6pd_auto_sla_id (__main__.BondingInterfaceTest) ... ok
+  test_dhcpv6pd_manual_sla_id (__main__.BondingInterfaceTest) ... ok
+  test_interface_description (__main__.BondingInterfaceTest) ... ok
+  test_interface_disable (__main__.BondingInterfaceTest) ... ok
+  test_interface_ip_options (__main__.BondingInterfaceTest) ... ok
+  test_interface_ipv6_options (__main__.BondingInterfaceTest) ... ok
+  test_interface_mtu (__main__.BondingInterfaceTest) ... ok
+  test_ipv6_link_local_address (__main__.BondingInterfaceTest) ... ok
+  test_mtu_1200_no_ipv6_interface (__main__.BondingInterfaceTest) ... ok
+  test_span_mirror (__main__.BondingInterfaceTest) ... ok
+  test_vif_8021q_interfaces (__main__.BondingInterfaceTest) ... ok
+  test_vif_8021q_lower_up_down (__main__.BondingInterfaceTest) ... ok
+  test_vif_8021q_mtu_limits (__main__.BondingInterfaceTest) ... ok
+  test_vif_8021q_qos_change (__main__.BondingInterfaceTest) ... ok
+  test_vif_s_8021ad_vlan_interfaces (__main__.BondingInterfaceTest) ... ok
+  test_vif_s_protocol_change (__main__.BondingInterfaceTest) ... ok
+
+  ----------------------------------------------------------------------
+  Ran 23 tests in 244.694s
+
+  OK
+
+This will limit the `bond` interface test to use only `eth1` and `eth2`
+as member ports.
+
+Config Load Tests
+=================
+
+The other part of our tests are called "config load tests." Config load tests
+sequentially load arbitrary configuration files to verify that configuration
+migration scripts work as designed and that a given set of functionality can
+still be loaded with a fresh VyOS ISO image.
+
+The configurations are all derived from production systems and can act as
+test cases or as references for enabling certain features. The configurations
+can be found here:
+https://github.com/vyos/vyos-1x/tree/current/smoketest/configs
+
+The entire test is controlled by the main wrapper script
+``/usr/bin/vyos-configtest``.
+It behaves in the same way as the main smoketest script. It scans the folder
+for potential configuration files and issues a ``load`` command for each file.
+
+Manual config load test
+-----------------------
+
+You do not have to load all configurations sequentially; you can also load
+individual test configurations manually.
+
+.. code-block:: none
+
+  vyos@vyos:~$ configure
+  load[edit]
+
+  vyos@vyos# load /usr/libexec/vyos/tests/config/ospf-small
+  Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small'
+  Load complete. Use 'commit' to make changes effective.
+  [edit]
+  vyos@vyos# compare
+  [edit interfaces ethernet eth0]
+  -hw-id 00:50:56:bf:c5:6d
+  [edit interfaces ethernet eth1]
+  +duplex auto
+  -hw-id 00:50:56:b3:38:c5
+  +speed auto
+  [edit interfaces]
+  -ethernet eth2 {
+  -    hw-id 00:50:56:b3:9c:1d
+  -}
+  -vti vti1 {
+  -    address 192.0.2.1/30
+  -}
+  ...
+
+  vyos@vyos# commit
+  vyos@vyos#
+
+.. note:: Some configurations have preconditions that must be met. These most
+  likely include generation of cryptographic keys before the config can be
+  applied; otherwise, you will get a commit error. If you are interested in
+  how those preconditions are fulfilled, check the vyos-build_ repository and
+  the ``scripts/check-qemu-install`` file.
+
+.. include:: /_include/common-references.txt