Skip to content

Commit

Permalink
[Docs] Add maintainer's manual and version script
Browse files Browse the repository at this point in the history
Signed-off-by: Wojtek Porczyk <[email protected]>
  • Loading branch information
woju committed Feb 27, 2024
1 parent 0ca3cbd commit e292f31
Show file tree
Hide file tree
Showing 4 changed files with 262 additions and 0 deletions.
5 changes: 5 additions & 0 deletions Documentation/devel/DCO/index.rst
Original file line number Diff line number Diff line change
@@ -1 +1,6 @@
.. include:: ../../../DCO

.. note::

For cryptographical “code signing”, as opposed to “signing off” your
commits, please refer to :doc:`../maintainer-manual`.
175 changes: 175 additions & 0 deletions Documentation/devel/maintainer-manual.rst
Original file line number Diff line number Diff line change
@@ -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 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
<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.
1 change: 1 addition & 0 deletions Documentation/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,7 @@ Indices and tables
devel/contributing
devel/onboarding
devel/setup
devel/maintainer-manual
devel/coding-style
devel/howto-doc
devel/charter
Expand Down
81 changes: 81 additions & 0 deletions scripts/release.sh
Original file line number Diff line number Diff line change
@@ -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"

0 comments on commit e292f31

Please sign in to comment.