[PATCH rtems-libbsd] CONTRIBUTING: Sharpen priority development goals

Christian Mauderer christian.mauderer at embedded-brains.de
Fri Feb 3 07:31:46 UTC 2023

This patch tries to make the most important goals of LibBSD development
more clear based on the results of the discussion on the mailing list:

 CONTRIBUTING.rst | 39 ++++++++++++++++++++++++++++++---------
 1 file changed, 30 insertions(+), 9 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 0b6fc7a0..31561f6a 100644
@@ -21,15 +21,36 @@ RTEMS specific support files, general guidelines on what modifications to the
 FreeBSD source are permitted, and some other topics.  For building the library,
 see the `README <README.rst>`_.
-Goals of the LibBSD activity are
-* provide functionality from FreeBSD to RTEMS,
-* ease updating to future FreeBSD versions,
-* ease tracking changes in FreeBSD code,
-* minimize manual changes in FreeBSD code.
-We will work to push our changes upstream to the FreeBSD Project and minimize
-changes required at each update point.
+Every change to LibBSD has to consider the following points in groups of
+descending priority:
+#. Real-time Impacts + Maintainability Loss
+   * LibBSD itself doesn't make any real time claims because it is basically
+     FreeBSD and they don't make any real time claims either.  But all
+     development in LibBSD must make sure that the real time ability of the
+     RTEMS core system or the application is not affected.
+   * It's utterly important that LibBSD is simple to maintain.  One of the most
+     important points for that is that upgrades to newer FreeBSD versions have
+     to be easy.
+#. Transparency Loss + Modularity Loss + Code/RAM Size Increase
+   * LibBSD code should be easy to read and easy to debug.  Changes should be
+     integrated in a way that are easy to understand.  Of course that's a
+     subjective goal.  As a general rule: If it adds lot's of extra code or even
+     more layers than already exist in FreeBSD, it's harder to understand.
+   * There are a number of methods used in LibBSD to make it modular.  If you
+     add new functionality, use one of the existing methods to allow enabling or
+     disabling your module.  For example make sure that the linker can remove
+     unused modules.  If that doesn't work for your feature, try to use the
+     buildsets to allow to switch a module on or off.
+   * A lot of different hardware uses LibBSD as network or USB stack or maybe in
+     the future even only for other subsystems.  Some of the targets have
+     hundreds of megabytes memory.  Others can only have a few megabytes (like
+     the ATSAMV71).  Make sure that changes don't increase the RAM / Flash size
+     of the default build so that it can't be used on the small targets.
+#. Performance Loss
+   * There are applications, that require (for example) a high network
+     throughput or a fast storage access.  Make sure to take that into account
+     if adding changes.
 What is in the Git Repository

More information about the devel mailing list