[Docs] Add maintainer's manual and version script

Signed-off-by: Wojtek Porczyk <[email protected]>

Documentation/devel/DCO/index.rst

@@ -1 +1,6 @@
 .. include:: ../../../DCO
+
+.. note::
+
+    For cryptographical “code signing”, as opposed to “signing off” your
+    commits, please refer to :doc:`../maintainer-manual`.

Documentation/devel/maintainer-manual.rst

@@ -0,0 +1,175 @@
+Maintainer's manual
+===================
+
+Release process
+---------------
+
+Create new checklist issue (fill all ``<variable>`` before submitting):
+
+..
+    # query string can be regenerated:
+    import urllib.parse
+    urllib.parse.urlencode([
+        ('title', 'Release <version> checklist'),
+        ('body', '''
+    ...
+        ''')])
+
+https://github.com/gramineproject/gramine/issues/new?title=Release+%3Cversion%3E+TODO&body=-+%5B+%5D+draft+release+notes+%28%40%3Cowner%3E%29%0A-+%5B+%5D+draft+blogpost+%28%40%3Cowner%3E%29%0A-+%5B+%5D+draft+%23community+announcement+%28%40%3Cowner%3E%29%0A-+%5B+%5D+update+installation+instructions+%28if+a+distro+was+released+since+last+release%29+%28%40%3Cowner%3E%29%0A-+%5B+%5D+create+release+PR+%28%40%3Cowner%3E%29%0A%0Aiterate+%28update+version%2C+build+and+upload+unstable+packages%29%0A%0Afinal+stretch%3A%0A-+%5B+%5D+get+QA+signoff+%28%40%3Cowner%3E%29%0A-+%5B+%5D+approve+PR+%28%40%3Cowner%3E%29%0A-+%5B+%5D+update+version+to+final+and+push+commits+%28%40%3Cowner%3E%29%0A-+%5B+%5D+build+final+packages+%28%40%3Cowner%3E%29%0A-+%5B+%5D+upload+packages+to+release+notes+%28%40%3Cowner%3E%29%0A-+%5B+%5D+push+tag+%28%40%3Cowner%3E%29%0A-+%5B+%5D+switch+release+notes+to+pushed+tag+%28%40%3Cowner%3E%29%0A-+%5B+%5D+merge+PR+%28%40%3Cowner%3E%29%0A-+%5B+%5D+publish+release+notes+%28%40%3Cowner%3E%29%0A-+%5B+%5D+publish+blogpost+%28%40%3Cowner%3E%29%0A-+%5B+%5D+publish+on+%23community+%28%40%3Cowner%3E%29%0A
+
+Create PR
+^^^^^^^^^
+
+.. code-block::
+
+    git checkout -b <owner>/release-<X.Y>
+    scripts/release.sh <X.Y>~rc1
+    git push -u origin <owner>/release-<X.Y>
+    firefox https://github.com/gramineproject/gramine/pull/new/<owner>/release-<X.Y>
+
+Then set the PR on reviewable.io to be reviewed commit-by-commit.
+
+Update version in PR
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+    git reset --hard HEAD~
+    scripts/release.sh X.Y~rcN
+    git push --force
+
+Tag
+^^^
+
+.. code-block::
+
+    git tag -m "Gramine <X.Y>" v<X.Y> HEAD~
+    git push v<X.Y>
+
+Code signing
+------------
+
+.. note::
+
+    “Code signing” is not to be confused with “signing off” your commits.
+
+    “Signing off” is a |~| legal device for a sort of signature by which you
+    assert that you are holding copyrights to the code you're submitting (or
+    your're authorized by copyright holder to submit the code). “Signing off” is
+    done by writing ``Signed-off-by:`` line to the commit message (maybe using
+    :command:`git commit -s`) and does not carry a separate cryptographic
+    signature. For details, please read :doc:`DCO/index`.
+
+    “Code signing” refers to the process of cryptographically siging your
+    contributions (commits and tags), so other people are able to mathematically
+    prove that the contribution came from the holder of a |~| particular
+    cryptographic key. It has no legal meaning. It can be done using
+    :command:`git commit -S` or by configuring :program:`git` (see below).
+
+Generating key
+^^^^^^^^^^^^^^
+First, you need to generate you key using :program:`gpg`. The key needs to be
+"sign only"! Otherwise, if you also add encrypt capability, people will add your
+key to their :abbr:`MUA (Mail User Agent)`\ s and will encrypt e-mail messages
+to you using code signing key. This is not desired, the key generated for the
+purpose of code signing should not be used in any other context (e.g. e-mail or
+singing code in other projects).
+
+In user ID, please write your name and comment saying that the key is meant for
+code signing in this project.
+
+The key needs to be RSA (at least 3072 to match overall security level in SGX)
+or Curve25519. 25519 keys are preferred, because they are smaller and faster to
+use. In some versions of :program:`gpg` you need to use ``--full-gen-key
+--expert`` to be able to choose ECC keys.
+
+.. code-block::
+
+    % gpg --full-gen-key --expert
+    gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc.
+    This is free software: you are free to change and redistribute it.
+    There is NO WARRANTY, to the extent permitted by law.
+
+    Please select what kind of key you want:
+       (1) RSA and RSA (default)
+       (2) DSA and Elgamal
+       (3) DSA (sign only)
+       (4) RSA (sign only)
+       (7) DSA (set your own capabilities)
+       (8) RSA (set your own capabilities)
+       (9) ECC and ECC
+      (10) ECC (sign only)
+      (11) ECC (set your own capabilities)
+      (13) Existing key
+      (14) Existing key from card
+    Your selection? 10
+    Please select which elliptic curve you want:
+       (1) Curve 25519
+       (3) NIST P-256
+       (4) NIST P-384
+       (5) NIST P-521
+       (6) Brainpool P-256
+       (7) Brainpool P-384
+       (8) Brainpool P-512
+       (9) secp256k1
+    Your selection? 1
+    Please specify how long the key should be valid.
+             0 = key does not expire
+          <n>  = key expires in n days
+          <n>w = key expires in n weeks
+          <n>m = key expires in n months
+          <n>y = key expires in n years
+    Key is valid for? (0)
+    Key does not expire at all
+    Is this correct? (y/N) y
+
+    GnuPG needs to construct a user ID to identify your key.
+
+    Real name: Wojciech Porczyk
+    Email address: [email protected]
+    Comment: Gramine code signing key
+    You selected this USER-ID:
+        "Wojciech Porczyk (Gramine code signing key) <[email protected]>"
+
+    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
+    We need to generate a lot of random bytes. It is a good idea to perform
+    some other action (type on the keyboard, move the mouse, utilize the
+    disks) during the prime generation; this gives the random number
+    generator a better chance to gain enough entropy.
+    gpg: /home/user/.gnupg/trustdb.gpg: trustdb created
+    gpg: key 044D9664E7A77E16 marked as ultimately trusted
+    gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created
+    gpg: revocation certificate stored as '/home/user/.gnupg/openpgp-revocs.d/9C4D27D9157EF771A4283926044D9664E7A77E16.rev'
+    public and secret key created and signed.
+
+    pub   ed25519 2024-02-22 [SC]
+          9C4D27D9157EF771A4283926044D9664E7A77E16
+    uid                      Wojciech Porczyk (Gramine code signing key) <[email protected]>
+
+.. yes, this is actual log from generating my own key!
+
+Submitting key to GitHub
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account#adding-a-gpg-key
+
+Setting up git
+^^^^^^^^^^^^^^
+
+*(Substitute key ID for your own key. The following example matches key ID from
+the example generation listing.)*
+
+.. code-block:: sh
+
+    git config --global commit.gpgsign true
+    git config --global user.signingkey 9C4D27D9157EF771A4283926044D9664E7A77E16
+
+If you are using Split GPG feature of Qubes OS
+(https://www.qubes-os.org/doc/split-gpg/#using-git-with-split-gpg):
+
+.. code-block:: sh
+
+    git config --global gpg.program qubes-gpg-client-wrapper
+
+and remember to set ``QUBES_GPG_DOMAIN`` envrionment variable in your shell
+config file.

Documentation/index.rst

@@ -215,6 +215,7 @@ Indices and tables
    devel/contributing
    devel/onboarding
    devel/setup
+   devel/maintainer-manual
    devel/coding-style
    devel/howto-doc
    devel/charter

scripts/release.sh

@@ -0,0 +1,81 @@
+#!/bin/sh
+# SPDX-License-Identifier: LGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2024 Wojtek Porczyk <[email protected]>
+
+set -e
+
+: ${D:="bookworm bullseye jammy focal"}
+
+bump() {
+    v="$1"
+    test -n "$v"
+
+    find . -name meson.build \( -path \*/subprojects/\* -o -print \) \
+    | while read meson_build
+    do
+        printf 'patching %s\n' "$meson_build" >&2
+        sed -i -e "s/^\(\s*version: '\).*\(',\)$/\1$v\2/" "$meson_build"
+        git add "$meson_build"
+    done
+
+    echo patching debian/changelog >&2
+    d="$D"
+    case "$v" in
+    *~UNRELEASED)
+        d=UNRELEASED ;;
+    *~*)
+        d=$(printf %s "$d" | sed 's/\</unstable-/g') ;;
+    esac
+    if ! test "$(dpkg-parsechangelog -SVersion)" = "$v"
+    then
+        dch -b -v "$v" ""
+    fi
+    dch -r -D "$d" --force-distribution # this is interactive, will open editor
+    git add debian/changelog
+
+    if test -w gramine.spec
+    then
+        echo patching gramine.spec >&2
+        sed -i -e "s/^\(Version: \).*$/\1$v/" gramine.spec
+        git add gramine.spec
+    fi
+
+    if test -w packaging/alpine/APKBUILD
+    then
+        echo patching packaging/alpine/APKBUILD >&2
+        sed -i -e "s/^\(_real_pkgver=\).*$/\1$v/" packaging/alpine/APKBUILD
+        git add packaging/alpine/APKBUILD
+    fi
+}
+
+commit() {
+    v="$1"
+    test -n "$v"
+    shift
+
+    git commit --signoff --message "Bump version to $v" "$@"
+}
+
+
+if test -z "$1"
+then
+    echo usage: "$0" VERSION >&2
+    exit 2
+fi
+V="$1"
+VP="${1%~*}"post~UNRELEASED
+
+cd "$(git rev-parse --show-toplevel)"
+
+bump "$V"
+
+# to fix a mistake:
+#   git reset --hard HEAD~
+#   release.sh X.Y
+case "$(git log -n1 --format=%s)" in
+"Bump "*)   commit "$V" --amend ;;
+*)          commit "$V" ;;
+esac
+
+bump "$VP"
+commit "$VP"