From e292f31f4f70025ec686abdd4502f7ac45ec5317 Mon Sep 17 00:00:00 2001 From: Wojtek Porczyk Date: Fri, 23 Feb 2024 13:19:56 +0100 Subject: [PATCH] [Docs] Add maintainer's manual and version script Signed-off-by: Wojtek Porczyk --- Documentation/devel/DCO/index.rst | 5 + Documentation/devel/maintainer-manual.rst | 175 ++++++++++++++++++++++ Documentation/index.rst | 1 + scripts/release.sh | 81 ++++++++++ 4 files changed, 262 insertions(+) create mode 100644 Documentation/devel/maintainer-manual.rst create mode 100755 scripts/release.sh diff --git a/Documentation/devel/DCO/index.rst b/Documentation/devel/DCO/index.rst index 023eff9474..ca8542f4b8 100644 --- a/Documentation/devel/DCO/index.rst +++ b/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`. diff --git a/Documentation/devel/maintainer-manual.rst b/Documentation/devel/maintainer-manual.rst new file mode 100644 index 0000000000..121cd45f38 --- /dev/null +++ b/Documentation/devel/maintainer-manual.rst @@ -0,0 +1,175 @@ +Maintainer's manual +=================== + +Release process +--------------- + +Create new checklist issue (fill all ```` before submitting): + +.. + # query string can be regenerated: + import urllib.parse + urllib.parse.urlencode([ + ('title', 'Release 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 /release- + scripts/release.sh ~rc1 + git push -u origin /release- + firefox https://github.com/gramineproject/gramine/pull/new//release- + +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 " v HEAD~ + git push v + +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 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 need to be "sign +only"! Otherwise, if you also add encrypt capability, people will add your key +to their MUAs 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 + = key expires in n days + w = key expires in n weeks + m = key expires in n months + 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: woju@invisiblethingslab.com + Comment: Gramine code signing key + You selected this USER-ID: + "Wojciech Porczyk (Gramine code signing key) " + + 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) + +.. 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. diff --git a/Documentation/index.rst b/Documentation/index.rst index 7c977d8e8d..632e8b1c6e 100644 --- a/Documentation/index.rst +++ b/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 diff --git a/scripts/release.sh b/scripts/release.sh new file mode 100755 index 0000000000..5e43e85da3 --- /dev/null +++ b/scripts/release.sh @@ -0,0 +1,81 @@ +#!/bin/sh +# SPDX-License-Identifier: LGPL-3.0-or-later +# SPDX-FileCopyrightText: 2024 Wojtek Porczyk + +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/\&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"