From 4f32d35ca9ef88d285388248371ea0ace3b982f7 Mon Sep 17 00:00:00 2001 From: Mark Stapp Date: Tue, 16 Mar 2021 11:27:59 -0400 Subject: [PATCH 1/2] doc: fix warnings in dev docs Fix a couple of warnings in dev doc rst files. Signed-off-by: Mark Stapp --- doc/developer/cross-compiling.rst | 2 +- doc/developer/scripting.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/developer/cross-compiling.rst b/doc/developer/cross-compiling.rst index 339e00c921..3bf78f7633 100644 --- a/doc/developer/cross-compiling.rst +++ b/doc/developer/cross-compiling.rst @@ -189,7 +189,7 @@ later on to FRR. One may get burned when compiling gRPC if the ``protoc`` version on the build machine differs from the version of ``protoc`` being linked to during a gRPC build. The error messages from this defect look like: -.. code-block:: terminal +.. code-block:: shell gens/src/proto/grpc/channelz/channelz.pb.h: In member function ‘void grpc::channelz::v1::ServerRef::set_name(const char*, size_t)’: gens/src/proto/grpc/channelz/channelz.pb.h:9127:64: error: ‘EmptyDefault’ is not a member of ‘google::protobuf::internal::ArenaStringPtr’ diff --git a/doc/developer/scripting.rst b/doc/developer/scripting.rst index b0413619ab..708f65ff7d 100644 --- a/doc/developer/scripting.rst +++ b/doc/developer/scripting.rst @@ -271,7 +271,7 @@ has). For example, here is the encoder function for ``struct prefix``: This function pushes a single value onto the Lua stack. It is a table whose equivalent in Lua is: -.. code-block:: +.. code-block:: c { ["network"] = "1.2.3.4/24", ["prefixlen"] = 24, ["family"] = 2 } From b43be6b8f61becff18545471614fc8faa4c55c71 Mon Sep 17 00:00:00 2001 From: Mark Stapp Date: Tue, 16 Mar 2021 11:28:25 -0400 Subject: [PATCH 2/2] doc: add more notes about new topotests Add some extra notes to the dev doc section about writing new topotests: check for OS/kernel support if necessary; avoid volatile or unstable data like ifindices or link-locals. Signed-off-by: Mark Stapp --- doc/developer/subdir.am | 1 + doc/developer/topotests.rst | 18 +++++++++++++----- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am index f7e4486ef0..d16420c7e7 100644 --- a/doc/developer/subdir.am +++ b/doc/developer/subdir.am @@ -57,6 +57,7 @@ dev_RSTFILES = \ doc/developer/tracing.rst \ doc/developer/testing.rst \ doc/developer/topotests-snippets.rst \ + doc/developer/topotests-markers.rst \ doc/developer/topotests.rst \ doc/developer/workflow.rst \ doc/developer/xrefs.rst \ diff --git a/doc/developer/topotests.rst b/doc/developer/topotests.rst index 93d81548b2..7976a206f7 100644 --- a/doc/developer/topotests.rst +++ b/doc/developer/topotests.rst @@ -388,11 +388,19 @@ This is the recommended test writing routine: - Format the new code using `black `_ - Create a Pull Request -.. Note:: +Some things to keep in mind: + +- BGP tests MUST use generous convergence timeouts - you must ensure + that any test involving BGP uses a convergence timeout of at least + 130 seconds. +- Topotests are run on a range of Linux versions: if your test + requires some OS-specific capability (like mpls support, or vrf + support), there are test functions available in the libraries that + will help you determine whether your test should run or be skipped. +- Avoid including unstable data in your test: don't rely on link-local + addresses or ifindex values, for example, because these can change + from run to run. - BGP tests MUST use generous convergence timeouts - you must ensure - that any test involving BGP uses a convergence timeout of at least - 130 seconds. Topotest File Hierarchy """"""""""""""""""""""" @@ -795,7 +803,7 @@ Requirements: - Use `black `_ code formatter before creating a pull request. This ensures we have a unified code style. - Mark test modules with pytest markers depending on the daemons used during the - tests (s. Markers) + tests (see :ref:`topotests-markers`) Tips: