doc: introduce FRR community "accords"

The idea here is to pass "non-code agreements" through the PR review
mechanism, and have them visible in the git tree.

Two "example" (but real) accords are included, mostly to illustrate the
idea.  Both of these should be non-controversial and have had some
previous discussion in random places.

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

diff --git a/doc/accords/README.md b/doc/accords/README.md
new file mode 100644 (file)
index 0000000..0461b04
--- /dev/null
+++ b/doc/accords/README.md
@@ -0,0 +1,32 @@
+FRR accords
+===========
+
+
+This directory contains some text documents with "accords" agreed upon by the
+FRR community.  The idea here is that by passing text documents through the
+PR/review process, consensus for work items, design decisions, etc. can be
+established and documented.  They can also be changed later by followup PRs if
+consensus shifts.  This is intended to reduce friction, and provide more
+transparency for newcomers & less frequent contributors.
+
+Examples of things that could go here:
+
+- agreement on how to fix some deeper-seated existing shortcoming in FRR that
+  might take some time to fix, to get consensus before putting time into it.
+
+- larger design (especially system/package integration) decisions that are not
+  immediately tangible to the code.
+
+- scoping decisions, particularly negative (i.e. we decided at some point that
+  FRR is not the right place for something) - these are otherwise lost in some
+  ancient closed PR, and some new contributor might be unaware and waste time.
+
+Files in this directory are not formatted in any specific way and not rendered
+into documentation.  They're intended to be read with your code editor of
+choice.
+
+To avoid misunderstandings, there is one "rule" about wording:  the consensus
+actual is worded with "will", "going to", "is" - this reflects the idea that
+when the PR is merged, it *is* community consensus.  Words like "should",
+"would" or "might" should be limited to context and reference that is provided
+as rationale for the consensus.

diff --git a/doc/accords/frr-service-is-watchfrr b/doc/accords/frr-service-is-watchfrr
new file mode 100644 (file)
index 0000000..2301c83
--- /dev/null
+++ b/doc/accords/frr-service-is-watchfrr
@@ -0,0 +1,16 @@
+The "FRR" service unit is watchfrr
+==================================
+
+
+"FRR" on the distribution/OS level is one service (generally called "frr").
+Exposing individual daemons (zebra, staticd, bgpd, ...) as service units does
+not match FRR's internal expectations.
+
+At some future point, watchfrr will add functionality to receive "router bgp",
+"router ospf" etc. commands (or their YANG variants) and automatically start
+the required daemons.  In particular with multi-instance setups, this will
+simplify config (no more mucking around /etc/frr/daemons - if watchfrr
+understands which daemons are needed by a given config, the daemons file is
+pointless.)
+
+This to some degree assumes an "integrated-config world".

diff --git a/doc/accords/integrated-config-wins b/doc/accords/integrated-config-wins
new file mode 100644 (file)
index 0000000..5a02b99
--- /dev/null
+++ b/doc/accords/integrated-config-wins
@@ -0,0 +1,10 @@
+Integrated config wins
+======================
+
+
+The use of split-configuration setups (zebra.conf, staticd.conf, bgpd.conf,
+etc.) in FRR is considered deprecated and will go away at some point.
+
+At this point there is no timeline yet on removing split-config support, and
+this needs to go through an extensive deprecation period with increasingly
+loud user warnings.

diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst
index b8e298dd3c866fb5746f469b730446ff19bad1df..b0d320b5eaf4c045b718621cbdae40a08a3a4510 100644 (file)
--- a/doc/developer/workflow.rst
+++ b/doc/developer/workflow.rst
@@ -308,6 +308,21 @@ your changes is usually not required and will be added based on your commit
 messages by the maintainers. However, you are free to include an update to the
 changelog with some better description.
 
+Accords: non-code community consensus
+=====================================
+
+The FRR repository has a place for "accords" - these are items of
+consideration for FRR that influence how we work as a community, but either
+haven't resulted in code *yet*, or may *never* result in code being written.
+They are placed in the ``doc/accords/`` directory.
+
+The general idea is to simply pass small blurbs of text through our normal PR
+procedures, giving them the same visibility, comment and review mechanisms as
+code PRs - and changing them later is another PR.  Please refer to the README
+file in ``doc/accords/`` for further details.  The file names of items in that
+directory are hopefully helpful in determining whether some of them might be
+relevant to your work.
+
 Submitting Patches and Enhancements
 ===================================