Hi Rosemarie, thanks for the documentation update. I have some notes inline
On Tue, Aug 4, 2026 at 12:48 AM Rosemarie O'Riorden via dev <[email protected]> wrote: > > Fix various typos, inaccuracies, and missing information. > > Reported-at: https://redhat.atlassian.net/browse/FDP-3051 > Assisted-by: Claude Opus 4.6, Claude Code > Signed-off-by: Rosemarie O'Riorden <[email protected]> > --- > v1 -> v2: > - Add two minor typo fixes I forgot to include in v1. > --- > Documentation/topics/test-development.rst | 74 +++++++++++------------ > Documentation/topics/testing.rst | 12 ++-- > Documentation/tutorials/ovn-sandbox.rst | 2 +- > 3 files changed, 41 insertions(+), 47 deletions(-) > > diff --git a/Documentation/topics/test-development.rst > b/Documentation/topics/test-development.rst > index 823957983..0ecad1e7e 100644 > --- a/Documentation/topics/test-development.rst > +++ b/Documentation/topics/test-development.rst > @@ -61,7 +61,7 @@ check COMMAND... > > Function to run COMMAND and check that it succeeds without any output. Also > logs the COMMAND. Note that most ``ovn-nbctl`` and ``ovn-sbctl`` must be run > -withing ``check`` so that the return status is checked. > +within ``check`` so that the return status is checked. > > OVN_CHECK_PACKETS([PCAP], [EXPECTED]) > +++++++++++++++++++++++++++++++++++++ > @@ -102,8 +102,8 @@ uuid as output. It also fails if the output is empty. > Daemon/Sandbox Management > ~~~~~~~~~~~~~~~~~~~~~~~~~ > > -ovn_start [--backup-northd=none|paused] [AZ] > -++++++++++++++++++++++++++++++++++++++++++++ > +ovn_start [--backup-northd[=paused]] [--use-tcp-to-sb] [AZ] The notation used here makes it seem like you can pass both --backup-northd and --use-tcp-to-sb as options to ovn_start. ovn_start() will only actually read one such option passed to it. The notation should be something more like: ovn_start [--backup-northd[=paused] | --use-tcp-to-sb] [AZ] That all being said, I find it weird that --backup-northd and --use-tcp-to-sb are mutually exclusive options, but that's how it works. > +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Nit: The line of + symbols is supposed to be the same length as the title above it. This mistake is made a few times throughout this file. > > Creates and initializes ovn-sb and ovn-nb databases and starts their > ovsdb-server instance, sets appropriate environment variables so that > ovn-sbctl > @@ -129,7 +129,8 @@ ovn_attach NETWORK BRIDGE IP [MASKLEN] [ENCAP] > > First, this function attaches BRIDGE to interconnection network NETWORK. > Second, it configures (simulated) address IP (with network mask length > MASKLEN, > -which defaults to 24) on BRIDGE. Finally, it configures the Open vSwitch > +which defaults to 24) on BRIDGE. ENCAP specifies the tunnel encapsulation > types > +(defaults to ``geneve,vxlan``). Finally, it configures the Open vSwitch > database to work with OVN and starts ovn-controller. > > sim_add SANDBOX > @@ -156,7 +157,7 @@ or:: > as [OVS_DIR] COMMAND > ++++++++++++++++++++ > > -``as $1`` sets the ``OVS_*DIR`` and ``OVN_*DIR*`` environment variables to > +``as $1`` sets the ``OVS_*DIR`` and ``OVN_*DIR`` environment variables to > point to $ovs_base/$1. > > ``as $1 COMMAND...`` sets those variables in a subshell and invokes COMMAND > @@ -187,36 +188,30 @@ OVN_POPULATE_ARP() > ++++++++++++++++++ > > Macro to pre-populate the ARP tables of all of the OVN instances that have > been > -started with ```ovn_attach()``. That means that packets sent from one > +started with ``ovn_attach()``. That means that packets sent from one > hypervisor to another never get dropped or delayed by ARP resolution, which > makes testing easier. > > -OVS_TRAFFIC_VSWITCHD_START([vsctl-args], [vsctl-output], [=override]) > -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > +OVS_TRAFFIC_VSWITCHD_START([vsctl-args], [vsctl-output]) > +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > -Macro to create a database and starts ovsdb-server, starts ovs-vswitchd > -connected to that database, calls ovs-vsctl to create a bridge named br0 with > -predictable settings, passing 'vsctl-args' as additional commands to > -ovs-vsctl. If 'vsctl-args' causes ovs-vsctl to provide output (e.g. because > it > -includes "create" commands) then 'vsctl-output' specifies the expected output > -after filtering through uuidfilt. > - > -If a test needs to use "system" devices (as dummies), then specify > -``=override`` (literally) as the third argument. Otherwise, system devices > -won't work at all (which makes sense because tests should not access a > system's > -real Ethernet devices). > +Macro to create a database and start ovsdb-server, start ovs-vswitchd > connected > +to that database, and create a bridge named br0 with predictable settings. > +Additional ovs-vsctl commands can be passed via 'vsctl-args'. If those > commands > +produce output (e.g. "create" commands), 'vsctl-output' specifies the > expected > +output after filtering through uuidfilt. > > OVS_TRAFFIC_VSWITCHD_STOP([WHITELIST], [extra_cmds]) > ++++++++++++++++++++++++++++++++++++++++++++++++++++ > > -Macro to gracefully stops ovs-vswitchd and ovsdb-server, checking their log > +Macro to gracefully stop ovs-vswitchd and ovsdb-server, checking their log > files for messages with severity WARN or higher and signaling an error if any > is present. The optional WHITELIST may contain shell-quoted "sed" commands to > delete any warnings that are actually expected, e.g.:: > > OVS_TRAFFIC_VSWITCHD_STOP(["/expected error/d"]) > > -'extra_cmds' are shell commands to be executed afte OVS_VSWITCHD_STOP() is > +'extra_cmds' are shell commands to be executed after OVS_VSWITCHD_STOP() is > invoked. They can be used to perform additional cleanups such as name space > removal. > > @@ -240,35 +235,34 @@ and after recompute are the same. Optional arguments > may also contain > acceptable ``related_ports`` differences, datapaths and tables on which flow > differences are considered as acceptable. > > -OVN_CLEANUP_SBOX(sbox) > -++++++++++++++++++++++ > +OVN_CLEANUP_SBOX(sbox[, error[, related_ports[, ignored_dp[, > ignored_tables]]]]) This is missing the "no_recompute_check" option. > +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > Macro to gracefully terminate OVN daemons in the specified sandbox instance. > The sandbox name ``vtep`` is treated as a special case, and is assumed to > have > ovn-controller-vtep and ovs-vtep daemons running instead of ovn-controller. > > Also checks the log file for messages with severity WARN or > -higher and signals an error if any is present. Optional arguments may contain > -"acceptable" error messages. > +higher and signals an error if any is present. The 'error' argument may > contain > +sed commands to delete acceptable error messages. > > Before terminating the daemons, it also issues recomputes on ovn-controllers > in > -listed sandboxes, and checks whether the related ports and the openflows > before > -and after recompute are the same. Optional arguments may also contain > -acceptable ``related_ports`` differences, datapaths and tables on which flow > -differences are considered as acceptable. > +the sandbox, and checks whether the related ports and the openflows before > +and after recompute are the same. The 'related_ports', 'ignored_dp', and > +'ignored_tables' arguments specify acceptable differences. > > -OVN_CLEANUP_CONTROLLER(sbox) > -++++++++++++++++++++++++++++ > +OVN_CLEANUP_CONTROLLER(hv[, sbox[, related_ports[, ignored_dp[, > ignored_tables[, no_recompute_check]]]]]) > +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > Macro to gracefully terminate ovn-controller in the specified sandbox > -instance. The sandbox name ``vtep`` is treated as a special case, and is > -assumed to have ovn-controller-vtep and ovs-vtep daemons running instead of > -ovn-controller. > +instance. The 'hv' argument names the hypervisor; when it equals ``vtep``, > the > +macro stops ovn-controller-vtep and ovs-vtep instead of ovn-controller. The > +'sbox' argument names the sandbox directory (defaults to 'hv' when omitted). > > -Issues recomputes on ovn-controllers in listed sandbox, and checks whether > the > -related ports and the openflows before and after recompute are the same. > -Optional arguments may also contain acceptable ``related_ports`` differences, > -datapaths and tables on which flow differences are considered as acceptable. > +Unless 'no_recompute_check' is ``True``, issues recomputes on ovn-controller > +and checks whether the related ports and the openflows before and after > +recompute are the same. The 'related_ports', 'ignored_dp', and > +'ignored_tables' arguments specify acceptable differences. > > OVN_CLEANUP_IC([az ...]) > ++++++++++++++++++++++++ > @@ -314,7 +308,7 @@ RUN_OVN_NBCTL() > +++++++++++++++ > > Macro to execute a list of commands built by the ``OVN_NBCTL`` macro. The > list > -of commands is executed in a single invocation of ``ovn-nbctl`` > +of commands is executed in a single invocation of ``ovn-nbctl``. > > OVS_VSCTL(VSCTL_COMMAND) > ++++++++++++++++++++++++ > @@ -335,7 +329,7 @@ STDOUT on stdout, and prints STDERR on stderr. If this > doesn't happen within a > reasonable time limit, then the test fails. > > There is an ``OVS_WAIT_FOR_OUTPUT_UNQUOTED`` version of this macro that > expands > -shell ``$variables``, ``$(command)``, and so on. The plain version does not > +shell ``$variables``, ``$(command)``, and so on. The plain version does not. > > OVS_WAIT_UNTIL(COMMAND[, IF-FAILED]) > ++++++++++++++++++++++++++++++++++++ > diff --git a/Documentation/topics/testing.rst > b/Documentation/topics/testing.rst > index 579422ca0..74a2d9abe 100644 > --- a/Documentation/topics/testing.rst > +++ b/Documentation/topics/testing.rst > @@ -36,7 +36,7 @@ validating basic functionality of OVN. Before running any > of the tests > described here, you must bootstrap, configure and build OVN as > described in :doc:`/intro/install/general`. You do not need to install > OVN, Open vSwitch or to build or load the kernel module to run these test > -suites.You do not need supervisor privilege to run these test suites. > +suites. You do not need superuser privilege to run these test suites. > > Unit Tests > ~~~~~~~~~~ > @@ -78,7 +78,7 @@ To see a complete list of test options, run:: > $ make check TESTSUITEFLAGS=--help > > The results of a testing run are reported in ``tests/testsuite.log``. Report > -report test failures as bugs and include the ``testsuite.log`` in your > report. > +test failures as bugs and include the ``testsuite.log`` in your report. > > .. note:: > Sometimes a few tests may fail on some runs but not others. This is > usually a > @@ -266,7 +266,7 @@ cached. In order to force the tests to rebuild all these > objects, run:: > A typical workflow for a developer trying to improve the performance of OVN > would be the following: > > -0. Optional: Modify/add a performance test to buld the topology that you are > +0. Optional: Modify/add a performance test to build the topology that you are > benchmarking, if required. > 1. Run ``make check-perf TESTSUITEFLAGS="--rebuild"`` to generate cached > databases (and complete a test run). The results of each test run are > @@ -283,7 +283,7 @@ would be the following: > 2. Run ``make check-perf`` to measure the performance metric that you are > benchmarking against. If you are only using one test, you can specify the > test to run by adding the test number to the ``make`` command. > - (e.g. ``make check-perf TESTSUITEFLAGS="--rebuild <test number>"``) > + (e.g. ``make check-perf TESTSUITEFLAGS="<test number>"``) > 3. Modify OVN code to implement the change that you believe will improve the > performance. > 4. Go to Step 2. to continue making improvements. > @@ -447,12 +447,12 @@ CI Integration > Upgrade tests run automatically in GitHub Actions: > > *On Schedule (Weekly)* > - - Tests all supported versions (24.03, 24.09, 25.03, 25.09) > + - Tests all supported versions (25.03, 25.09, 26.03) The currently supported versions of OVN upstream are 24.03 (for critical fixes only), 25.09, and 26.03. 25.03 is not supported upstream any longer. > > Implementation Details > ++++++++++++++++++++++ > > -Test are run locally through ``check-upgrade`` Makefile target. > +Tests are run locally through ``check-upgrade`` Makefile target. > The flow for make check-upgrade is: > > - Makefile > diff --git a/Documentation/tutorials/ovn-sandbox.rst > b/Documentation/tutorials/ovn-sandbox.rst > index 4acc22cdd..ff519c986 100644 > --- a/Documentation/tutorials/ovn-sandbox.rst > +++ b/Documentation/tutorials/ovn-sandbox.rst > @@ -47,7 +47,7 @@ Running the sandbox does the following steps to the > environment: > 1. Creates the ``OVN_Northbound`` and ``OVN_Southbound`` databases as > described in > `ovn-nb(5)`_ and `ovn-sb(5)`_. > > -2. Creates a backup server for ``OVN_Southbond`` database. Sandbox launch > +2. Creates a backup server for ``OVN_Southbound`` database. Sandbox launch > screen provides the instructions on accessing the backup database. > However > access to the backup server is not required to go through the tutorial. > > -- > 2.54.0 > > _______________________________________________ > dev mailing list > [email protected] > https://mail.openvswitch.org/mailman/listinfo/ovs-dev > _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
