[boost] [release] Tags are not being used correctly

Subject: [boost] [release] Tags are not being used correctly
From: Michael Witten (mfwitten_at_[hidden])
Date: 2016-03-22 20:58:52

Before I begin, I would like to note that the engineering of source code is
separate from the engineering of the release of that source code.

If you are bored by the issues of the release process, then that's fine;
however, it's important to find people who *are* interested in honing that
process ever more.

What follows is meant to be both informative and speculative; I'm just sharing
ideas that might prove useful to discussion.

Now, consider the following:

  $ git clone https://github.com/boostorg/boost.git repo
  $ cd repo
  $ git describe master
  fatal: No annotated tags can describe '11da8f8fafc4ba6b3e577e63abb7dc45cb902e2f'.
  However, there were unannotated tags: try --tags.

Yikes! The super-project doesn't seem to use any annotated tags; indeed:

  $ git for-each-ref --format='%(tag)' | grep -v ^$ || echo none
  none

Why does this matter? Recall the following from the `git help tag' page:

  Tag objects (created with -a, -s, or -u) are called "annotated" tags;
  they contain a creation date, the tagger name and e-mail, a tagging
  message, and an optional GnuPG signature. Whereas a "lightweight" tag is
  simply a name for an object (usually a commit object).
  
  Annotated tags are meant for release while lightweight tags are meant
  for private or temporary object labels. For this reason, some git
  commands for naming objects (like `git describe') will ignore
  lightweight tags by default.

Pay particular attention to the second paragraph:

  Annotated tags are meant for release while lightweight tags are meant
  for private or temporary object labels.

By using just lightweight tags, this project is neglecting to publish
valuable information about a release:

  * When was the release officially tagged?
  * Who tagged the release?
  * Is there any important information particular to this tagging?
    The tag body could include the `Message-ID' of the announcement email.
  * Is this tagging *authentic*? Is this really the tag developers intended?

Getting the tags correct is foundational to further improvements in
the security of release management; it will certainly make it much
easier for the release team to integrate cryptographic signatures
into the process, because git supports them directly.

Given that this project uses centralized repositories to which multiple
people have write access, it would probably be prudent to designate
officially one person to be the lead release manager, who by widespread
convention will be the only one allowed to tag a release (including
a release candidate); naturally, each submodule could have its own
lead release manager.

To facilitate this designation, the lead release manager should publish
conspicuously (and widely) the public key associated with his or her
personal identity in this role (an impersonal, project-level private key is
unlikely to enjoy the inherently intense security incentives that surround
a personal private key); this publishing includes:

  * Emailing the Boost developer mailing list with the plaintext
    version of the public key.
    
  * Disseminating the public key via specialized services (such as PGP
    keyservers).
    
  * Providing on the Boost website links to independently archived
    versions of the public key (such as the aforementioned email as
    hosted on Gmane, and a keyserver's file, and the webpage's own
    file).
    
  * Making sure community members with whom he or she officially meets
    (say, at an industry conference), have the opportunity to review,
    to accept, and to publicly validate the public key (i.e., to create
    a web of trust).

  * etc.

I know, it sounds terrible; but, it's really not that bad.

Then, every public tag should probably be an annotated tag; ideally, the lead
release manager would cryptographically sign every such tag with his or her
personal private key.

Separately, this same key could (and probably should) also be used to
produce a single plaintext cryptographic signature with an embedded
plaintext message that includes a listing of SHA-256, SHA-1, and MD5 hashes
for the relevant release archives; this signature (and embedded message)
could be the entire body of the release's announcement email, or it could
be included in the body of the announcement email (and this email could
be explicitly referenced in the body of the annotated release tag, etc.).
Certainly, that signature and its associated message should be published
conspicuously alongside the release's downloadable files.

For now, I would suggest concentrating on improving the procedures of the
super-project, and then eventually using the resulting insight to help the
[release] managers of the various subprojects introduce similar improvements.

After all, it would appear that 116 submodules of the super-project
also do not employ any annotated tags whatsoever; to get a list of
those submodules, remove the final `| wc -l' from the following:

  $ git submodule update --init
  $ git submodule foreach --quiet '
      git for-each-ref --format="%(tag)" | grep -q -v ^$ || echo "$name"
    ' | wc -l
    116

Of the ones that *do* use annotated tags, the majority probably use them
inadequately, irregularly, or possibly without realizing it; just 3
submodules publish tags that are exclusively annotated:

  compute
  dll
  libs/hana

Those were found in the following list of submodules, each of which uses
at least one annotated tag:

  $ git submodule foreach --quiet '
      total=$(git tag | wc -l)
      git for-each-ref --format="%(tag)" | awk -v n="$name" -v t="$total" "
        /./ {tags[i++] = \$0}
        END {
          if (i==0) exit;
          printf(\"%s(%i/%i):\n\",n,i,t);
          for (x in tags) print(\"  \" tags[x]);
          print(\"\");
        }
      "
    '
  asio(4/48):
    asio-1.10.1
    asio-1.10.2
    asio-1.10.4
    asio-1.10.5

  compute(5/5):
    v0.1
    v0.2
    v0.3
    v0.4
    v0.5

  dll(5/5):
    boost-review
    v0.1
    v0.1_docs
    v0.2
    v0.2_docs

  filesystem(1/61):
    filesystem-2014-07-23

  geometry(2/21):
    geometry-1.56.0
    geometry-1.56.0-beta1

  libs/hana(7/7):
    v0.1
    v0.2.0
    v0.3.0
    v0.4.0
    v0.5.0
    v0.6.0
    v0.7.0

  icl(1/23):
    icl-2015-11-22

  interprocess(1/43):
    interprocess-1.56.00.b0

  intrusive(1/43):
    intrusive-1.56.00.b0

  odeint(4/15):
    v2.1
    v2.2
    v2.3
    v2.4

  optional(1/61):
    optional-2016-02-22

  system(2/44):
    system-2014-06-02
    system-2014-07-17

  type_index(4/11):
    v1.0
    v1.0_docs
    v3.0
    v3.0_html

  build(2/73):
    converted-develop
    converted-master

Sincerely,
Michael Witten