doc/workflow: prefer typesafe containers

The typesafe containers have been around for quite a while now and
haven't gone up in a blaze of flames, so let's add a "strong
recommendation" to use them for new code and refactors.

For the nhrpd custom lists I'm already working to remove them; meanwhile
the old skiplists are primarily used in RFAPI (4 users outside of that),
so those could be next.

What remains are the old `list_*` and `hash_*`, which have >300 and >100
users respectively, making them a much harder problem to tackle.  And
the new hash implementation doesn't have the same level of
debug/introspection yet (it's on my TODO.)

Signed-off-by: David Lamparter <equinox@opensourcerouting.org>

diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst
index c703be62fccc821588e5fc32722612c9d35c2e71..2ce5f5d1c8c9cd7d4ec82af4e415da2eb6f14cad 100644 (file)
--- a/doc/developer/workflow.rst
+++ b/doc/developer/workflow.rst
@@ -637,6 +637,39 @@ well as CERT or MISRA C guidelines may provide useful input on safe C code.
 However, these rules are not applied as-is;  some of them expressly collide
 with established practice.
 
+
+Container implementations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In particular to gain defensive coding benefits from better compiler type
+checks, there is a set of replacement container data structures to be found
+in :file:`lib/typesafe.h`.  They're documented under :ref:`lists`.
+
+Unfortunately, the FRR codebase is quite large, and migrating existing code to
+use these new structures is a tedious and far-reaching process (even if it
+can be automated with coccinelle, the patches would touch whole swaths of code
+and create tons of merge conflicts for ongoing work.)  Therefore, little
+existing code has been migrated.
+
+However, both **new code and refactors of existing code should use the new
+containers**.  If there are any reasons this can't be done, please work to
+remove these reasons (e.g. by adding necessary features to the new containers)
+rather than falling back to the old code.
+
+In order of likelyhood of removal, these are the old containers:
+
+- :file:`nhrpd/list.*`, ``hlist_*`` ⇒ ``DECLARE_LIST``
+- :file:`nhrpd/list.*`, ``list_*`` ⇒ ``DECLARE_DLIST``
+- :file:`lib/skiplist.*`, ``skiplist_*`` ⇒ ``DECLARE_SKIPLIST``
+- :file:`lib/*_queue.h` (BSD), ``SLIST_*`` ⇒ ``DECLARE_LIST``
+- :file:`lib/*_queue.h` (BSD), ``LIST_*`` ⇒ ``DECLARE_DLIST``
+- :file:`lib/*_queue.h` (BSD), ``STAILQ_*`` ⇒ ``DECLARE_LIST``
+- :file:`lib/*_queue.h` (BSD), ``TAILQ_*`` ⇒ ``DECLARE_DLIST``
+- :file:`lib/hash.*`, ``hash_*`` ⇒ ``DECLARE_HASH``
+- :file:`lib/linklist.*`, ``list_*`` ⇒ ``DECLARE_DLIST``
+- open-coded linked lists ⇒ ``DECLARE_LIST``/``DECLARE_DLIST``
+
+
 Code Formatting
 ---------------