Merge pull request #8268 from mjstapp/doc_dev_topo_notes

doc: add info to topotest dev doc

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’

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 }
 

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 \

doc/developer/topotests.rst

@@ -388,11 +388,19 @@ This is the recommended test writing routine:
 - Format the new code using `black <https://github.com/psf/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 <https://github.com/psf/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: