doc: add some Github workflow notes

Just writing down what seems to be established procedure.

Signed-off-by: David Lamparter <equinox@diac24.net>

diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst
index 11e6233e124d67c3ffaab80d04eb864a60edd02d..6885a41e0f4aeb4bd976a457b7af5fe739683171 100644 (file)
--- a/doc/developer/workflow.rst
+++ b/doc/developer/workflow.rst
@@ -353,6 +353,14 @@ After Submitting Your Changes
    -  An author must never delete or manually dismiss someone else's comments
       or review.  (A review may be overridden by agreement in the weekly
       technical meeting.)
+   -  When you have addressed someone's review comments, please click the
+      "re-request review" button (in the top-right corner of the PR page, next
+      to the reviewer's name, an icon that looks like "reload")
+   -  The responsibility for keeping a PR moving rests with the author at
+      least as long as there are either negative CI results or negative review
+      comments.  If you forget to mark a review comment as addressed (by
+      clicking re-request review), the reviewer may very well not notice and
+      won't come back to your PR.
    -  Automatically generated comments, e.g., those generated by CI systems,
       may be deleted by authors and others when such comments are not the most
       recent results from that automated comment source.
@@ -435,6 +443,24 @@ Guidelines for code review
   code change is large enough/significant enough to warrant such
   a requirement.
 
+For project members with merge permissions, the following patterns have
+emerged:
+
+- a PR with any reviews requesting changes may not be merged.
+
+- a PR with any negative CI result may not be merged.
+
+- an open "yellow" review mark ("review requested, but not done") should be
+  given some time (a few days up to weeks, depending on the size of the PR),
+  but is not a merge blocker.
+
+- a "textbubble" review mark ("review comments, but not positive/negative")
+  should be read through but is not a merge blocker.
+
+- non-trivial PRs are generally given some time (again depending on the size)
+  for people to mark an interest in reviewing.  Trivial PRs may be merged
+  immediately when CI is green.
+
 
 Coding Practices & Style
 ========================