Re: [PATCH v2] embargoed releases: also describe the git-security list and the process

[Junio C Hamano <gitster@pobox.com>]

"Julia Ramer via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Ramer <gitprplr@gmail.com>
>
> With the recent turnover on the git-security list, questions came up how
> things are usually run. Rather than answering questions individually,
> extend Git's existing documentation about security vulnerabilities to
> describe the git-security mailing list, how things are run on that list,
> and what to expect throughout the process from the time a security bug
> is reported all the way to the time when a fix is released.
>
> Signed-off-by: Julia Ramer <gitprplr@gmail.com>
> ---

Thanks for an update that is excellently written.

I had only some minor points and random thoughts while reading it.
I do not know if all of them need to result in further changes to
the document, though.

 + The 'stakeholders' are explained twice in a bit different terms.
   The former (owners of products affected by vulnerabilities)
   description is more broad than the latter and would be more
   appropriate in general.  Perhaps dropping the latter would give
   us more clarity?

 - Would a reader, who has "stake" in the healty and secure Git, be
   helped if we spell out that they are welcome to ask joining the
   security list and how?  It feels a bit too obvious after reading
   "anybody may contact", which is both the right way to self
   nominate for the membership and the natural thing I expect such a
   reader would do, so we may not need to.

 + The packager whose release artifacts can be exchanged among
   security list participants under embargo is not limited to Git
   for Windows, even though we've only seen exchanges between
   Victoria and Veronica this cycle for that particular
   distribution.

 - The world is not limited to only Windows, mac and Linux.  Windows
   is not all that special.

 + The project maintainer is special in only two ways (tagging and
   producing release tarballs); in all the other contexts, treat him
   just like any other contributors.

 - There may be ways to improve on the lack of formal process to
   record decisions (e.g. a capable project secretary can notice
   that stakeholders agreed on a proposed release date, and send a
   separate message summarizing only that fact so that it would not
   be missed by casual bystanders), but that is something we should
   work on elsewhere, not as part of the effort to document the
   current practice.

 - I wonder if we want to record the name that is used to refer to
   the "private repository controlled by the project" on the
   security mailing list somewhere in the documentation.  If you are
   a stakeholder, being on the mailing list *and* having access to
   that repository are two things we need to make sure you have to
   partcipate in the coordinated embargoed releases.

 + Usually the fixes affect 'maint' and its tip is pointed by one of
   the tags for the security update release, and 'master' is updated
   to contain 'maint', but on the 'master' track there is no tag for
   the security update.  Other integration branches like 'next' and
   'seen' are also updated to contain the fix.

 + The "How we coordinate embargoed releases" section looked a bit
   odd to appear this late in the document.  Shouldn't it be moved
   way higher, even before we start talking about the security list?
   After all, the security mailing list is a means to the end that
   the section talks about (i.e. we sometimes need embargoed release
   process working behind closed doors).

Here is a patch that summarises some of the above on top of your
patch.  I only tried to address the bullet items with "+" in front
in the above list.


 .../howto/coordinate-embargoed-releases.txt        | 52 ++++++++++++----------
 1 file changed, 28 insertions(+), 24 deletions(-)

diff --git c/Documentation/howto/coordinate-embargoed-releases.txt w/Documentation/howto/coordinate-embargoed-releases.txt
index a01398c82b..80af5de297 100644
--- c/Documentation/howto/coordinate-embargoed-releases.txt
+++ w/Documentation/howto/coordinate-embargoed-releases.txt
@@ -3,6 +3,15 @@ Abstract: When a vulnerability is reported, we follow these guidelines to
  assess the vulnerability, create and review a fix, and coordinate embargoed
  security releases.
 
+How we coordinate embargoed releases
+------------------------------------
+
+To protect Git users from critical vulnerabilities, we do not just release
+fixed versions like regular maintenance releases. Instead, we coordinate
+releases with packagers, keeping the fixes under an embargo until the release
+date. That way, users will have a chance to upgrade on that date, no matter
+what Operating System or distribution they run.
+
 The `git-security` mailing list
 -------------------------------
 
@@ -50,10 +59,11 @@ A bug's life: Typical timeline
 
 - A bug is reported to the `git-security` mailing list.
 
-- Within a couple of days, someone from the core Git team responds with an
-  initial assessment of the bug’s severity.
+- Within a couple of days, someone from the core Git team, including
+  the Git maintainer, responds with an initial assessment of the
+  bug’s severity.
 
-- Other core developers - including the Git maintainer - chime in.
+- Other core developers chime in.
 
 - After discussion, if consensus is reached that the bug is not critical enough
   to warrant any embargo, the reporter is redirected to the public Git mailing
@@ -74,9 +84,11 @@ A bug's life: Typical timeline
   the patches are ready, the Git maintainer, and others determine a release date
   as well as the release trains that are serviced. The decision regarding which
   versions need a backported fix is based on input from the reporter, the
-  contributor who worked on the patches, and from stakeholders (e.g. operators
+  contributor who worked on the patches, and from stakeholders.   Operators
   of hosting sites who may want to analyze whether the given bug is exploited
-  via any of the repositories they host).
+  via any of the repositories they host, and binary packagers who want to
+  make sure their product gets patched adequately against the vulnerability,
+  for example, may want to give their input at this stage.
 
 - While the Git community does its best to accommodate the specific timeline
   requests of the various binary packagers, the nature of the issue may preclude
@@ -90,18 +102,19 @@ A bug's life: Typical timeline
 - The tags are created by the Git maintainer and pushed to the same
   repositories.
 
-- The Git for Windows, Git for macOS, BSD, Debian, etc maintainers prepares the
+- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepares the
   corresponding release artifacts, based on the tags created that have been
   prepared by the Git maintainer.
 
-- Git for Windows release artifacts are made available under embargo to
-  stakeholders via a mail to the `git-security` list.
+- The release artifacts prepared by various binary packagers can be
+  made available to stakeholders under embargo via a mail to the
+  `git-security` list.
 
 - Less than a week before the release, a mail with the relevant information is
   sent to <distros@vs.openwall.org> (see below), a list used to pre-announce
   embargoed releases of open source projects to the stakeholders of all major
-  Linux distributions. This includes a Git bundle of the tagged version(s), but
-  no further specifics of the vulnerability.
+  distributions of Linux as well as other OSes. This includes a Git bundle
+  of the tagged version(s), but no further specifics of the vulnerability.
 
 - Public communication is then prepared in advance of the release date. This
   includes blog posts and mails to the Git and Git for Windows mailing lists.
@@ -117,8 +130,8 @@ A bug's life: Typical timeline
 - Git for Windows release is then announced via a mail to the public Git and
   Git for Windows mailing lists as well as via a tweet.
 
-- Ditto for Linux distribution packagers: their releases are announced via
-  their preferred channels.
+- Ditto for distribution packagers for Linux and other platforms:
+  their releases are announced via their preferred channels.
 
 - A mail to <oss-security@lists.openwall.org> (see below for details) is sent
   as a follow-up to the <distros@vs.openwall.org> one, describing the
@@ -127,17 +140,8 @@ A bug's life: Typical timeline
 Note: The Git project makes no guarantees about timelines, but aims to keep
 embargoes reasonably short in the interest of keeping Git's users safe.
 
-How we coordinate embargoed releases
-------------------------------------
-
-To protect Git users from critical vulnerabilities, we do not just release
-fixed versions like regular maintenance releases. Instead, we coordinate
-releases with packagers, keeping the fixes under an embargo until the release
-date. That way, users will have a chance to upgrade on that date, no matter
-what Operating System or distribution they run.
-
-Open a Security Advisory draft
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Opening a Security Advisory draft
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The first step is to https://github.com/git/git/security/advisories/new[open
 an advisory]. Technically, this is not necessary. However, it is the most
@@ -239,4 +243,4 @@ it goes to <developer>.
 
 Thanks,
 <name>
-....
\ No newline at end of file
+....