9 files changed, 40 insertions, 8 deletions
diff --git a/doc/developer/building-frr-for-centos6.rst b/doc/developer/building-frr-for-centos6.rst
index ee0ffc2bf7..3d9edbe3a1 100644
--- a/doc/developer/building-frr-for-centos6.rst
+++ b/doc/developer/building-frr-for-centos6.rst
@@ -45,7 +45,7 @@ Add packages:
 
    sudo yum install git autoconf automake libtool make \
       readline-devel texinfo net-snmp-devel groff pkgconfig \
-      json-c-devel pam-devel flex epel-release c-ares-devel
+      json-c-devel pam-devel flex epel-release c-ares-devel libcap-devel
 
 Install newer version of bison (CentOS 6 package source is too old) from CentOS
 7:
diff --git a/doc/developer/building-frr-for-centos7.rst b/doc/developer/building-frr-for-centos7.rst
index 67f71bc3a5..cd90d41ffb 100644
--- a/doc/developer/building-frr-for-centos7.rst
+++ b/doc/developer/building-frr-for-centos7.rst
@@ -21,7 +21,7 @@ Add packages:
     sudo yum install git autoconf automake libtool make \
       readline-devel texinfo net-snmp-devel groff pkgconfig \
       json-c-devel pam-devel bison flex pytest c-ares-devel \
-      python-devel systemd-devel python-sphinx
+      python-devel systemd-devel python-sphinx libcap-devel
 
 .. include:: building-libyang.rst
 
diff --git a/doc/developer/building-frr-for-debian8.rst b/doc/developer/building-frr-for-debian8.rst
index 76f927853d..c12bf46f8d 100644
--- a/doc/developer/building-frr-for-debian8.rst
+++ b/doc/developer/building-frr-for-debian8.rst
@@ -18,7 +18,7 @@ Add packages:
    sudo apt-get install git autoconf automake libtool make \
       libreadline-dev texinfo libjson-c-dev pkg-config bison flex python3-pip \
       libc-ares-dev python3-dev python3-sphinx build-essential libsystemd-dev \
-      libsnmp-dev
+      libsnmp-dev libcap-dev
 
 Install newer pytest (>3.0) from pip
 
diff --git a/doc/developer/building-frr-for-debian9.rst b/doc/developer/building-frr-for-debian9.rst
index e58c59f451..f976b9f49a 100644
--- a/doc/developer/building-frr-for-debian9.rst
+++ b/doc/developer/building-frr-for-debian9.rst
@@ -11,7 +11,7 @@ Add packages:
    sudo apt-get install git autoconf automake libtool make \
      libreadline-dev texinfo libjson-c-dev pkg-config bison flex \
      libc-ares-dev python3-dev python3-pytest python3-sphinx build-essential \
-     libsnmp-dev libsystemd-dev
+     libsnmp-dev libsystemd-dev libcap-dev
 
 .. include:: building-libyang.rst
 
diff --git a/doc/developer/building-frr-for-fedora.rst b/doc/developer/building-frr-for-fedora.rst
index 0bfd43e93c..d8405eb351 100644
--- a/doc/developer/building-frr-for-fedora.rst
+++ b/doc/developer/building-frr-for-fedora.rst
@@ -14,7 +14,7 @@ Installing Dependencies
    sudo dnf install git autoconf automake libtool make \
      readline-devel texinfo net-snmp-devel groff pkgconfig json-c-devel \
      pam-devel python3-pytest bison flex c-ares-devel python3-devel \
-     python3-sphinx perl-core patch systemd-devel
+     python3-sphinx perl-core patch systemd-devel libcap-devel
 
 .. include:: building-libyang.rst
 
diff --git a/doc/developer/building-frr-for-ubuntu1404.rst b/doc/developer/building-frr-for-ubuntu1404.rst
index 569b3bded1..cc54415266 100644
--- a/doc/developer/building-frr-for-ubuntu1404.rst
+++ b/doc/developer/building-frr-for-ubuntu1404.rst
@@ -14,7 +14,7 @@ Installing Dependencies
       git autoconf automake libtool make libreadline-dev texinfo \
       pkg-config libpam0g-dev libjson-c-dev bison flex python3-pytest \
       libc-ares-dev python3-dev python3-sphinx install-info build-essential \
-      libsnmp-dev perl
+      libsnmp-dev perl libcap-dev
 
 .. include:: building-libyang.rst
 
diff --git a/doc/developer/building-frr-for-ubuntu1604.rst b/doc/developer/building-frr-for-ubuntu1604.rst
index 03852a62aa..63c6f8648c 100644
--- a/doc/developer/building-frr-for-ubuntu1604.rst
+++ b/doc/developer/building-frr-for-ubuntu1604.rst
@@ -14,7 +14,7 @@ Installing Dependencies
       git autoconf automake libtool make libreadline-dev texinfo \
       pkg-config libpam0g-dev libjson-c-dev bison flex python3-pytest \
       libc-ares-dev python3-dev libsystemd-dev python-ipaddress python3-sphinx \
-      install-info build-essential libsystemd-dev libsnmp-dev perl
+      install-info build-essential libsystemd-dev libsnmp-dev perl libcap-dev
 
 .. include:: building-libyang.rst
 
diff --git a/doc/developer/building-frr-for-ubuntu1804.rst b/doc/developer/building-frr-for-ubuntu1804.rst
index 96c0efe02a..9d85957d88 100644
--- a/doc/developer/building-frr-for-ubuntu1804.rst
+++ b/doc/developer/building-frr-for-ubuntu1804.rst
@@ -14,7 +14,7 @@ Installing Dependencies
       git autoconf automake libtool make libreadline-dev texinfo \
       pkg-config libpam0g-dev libjson-c-dev bison flex python3-pytest \
       libc-ares-dev python3-dev libsystemd-dev python-ipaddress python3-sphinx \
-      install-info build-essential libsystemd-dev libsnmp-dev perl
+      install-info build-essential libsystemd-dev libsnmp-dev perl libcap-dev
 
 .. include:: building-libyang.rst
 
diff --git a/doc/developer/lists.rst b/doc/developer/lists.rst
index fc47a67e42..5f020060ce 100644
--- a/doc/developer/lists.rst
+++ b/doc/developer/lists.rst
@@ -611,6 +611,38 @@ Head removal (pop) and deallocation:
     * note nothing between wrlock() and unlock() */
    XFREE(MTYPE_ITEM, i);
 
+FAQ
+---
+
+Why is the list head not ``const`` in the list APIs?
+   The semantics that a ``const`` list head would imply are not obvious.  It
+   could mean any of the following:
+
+    * the list just shouldn't be allocated/deallocated, but may be modified.
+      This doesn't actually work since the list head needs to be modified for
+      inserting or deleting items.
+
+    * the list shouldn't be modified, but items can.  This may make sense for
+      iterating, but it's not exactly consistent - an item might be on more
+      than one list, does it apply to all of them?  If not, which one?
+
+    * neither the list nor the items should be modified.  This is consistent,
+      but hard to do without creating a ``const`` copy of every single list
+      function.  Ease of use trumps this.
+
+Why is there no "is this item on a/the list" test?
+   It's slow for several of the data structures, and the work of adding it
+   just hasn't been done.  It can certainly be added if it's needed.
+
+Why is it ``PREDECL`` + ``DECLARE`` instead of ``DECLARE`` + ``DEFINE``?
+   The rule is that a ``DEFINE`` must be in a ``.c`` file, and linked exactly
+   once because it defines some kind of global symbol.  This is not the case
+   for the data structure macros;  they only define ``static`` symbols and it
+   is perfectly fine to include both ``PREDECL`` and ``DECLARE`` in a header
+   file.  It is also perfectly fine to have the same ``DECLARE`` statement in
+   2 ``.c`` files, but only **if the macro arguments are identical.**  Maybe
+   don't do that unless you really need it.
+
 FRR lists
 ---------