Reviewing patches from contributors to help Guix
Submission review
Functionality review
Code review
Check the patches contents are correct:
Check the patches works
Check the patches code is correct.
Inputs & native-inputs
Build system
Build phases
Stacked Git
(stgit)
Git
worktrees
send-email
Package
Structure
Source &
Origin
Advanced References
Building Guix from Source
Tools
bts & b4
Package
Patch
Review
Shell
Command
Build
Command
Package
Transforms
Manifests
Transforms in Manifests
Build Guix from source
Send the updated package
Alter the package we want to change
Build Guix from source
A series of
manual steps
Alter the package we want to change and verify to project standards
Send the updated package as a patch by email
Build Guix from source
A series of involved
manual steps
Alter the package we want to change and verify to project standards
Send the updated package as a patch by email
Guix installation
Ability to send email using git send-email
guix package: git:send-email
Tool - Stacked Git
Deals with patches in git as a stack
How we develop and how a Maintainer applies the patches is the same with the system
guix package: stgit@2.4.0
Tool - Mumi or b4
Both download patches so we can apply them locally
$ guix refresh --list-dependent <package>
to: control@debbugs.gnu.org
subject: <anything you want>
owner NNNN !
quit
# all my guix code is in this location:
$ cd ~/workspace/guix-packages
$ git clone https://git.savannah.gnu.org/git/guix.git guix
$ cd guix
$ cd <source location>
$ guix shell --container --nesting --development guix --share=/var/log/guix
[env] $ ./bootstrap
[env] $ ./configure
[env] $ make -j 24
Git clone the Guix archive:
Build the source:
$ git config user.name "Your Name"
$ git config user.email "your@email.address"
# config for the b4 patch tool
# turns off gpg attestation
$ git config b4.attestation-policy off
# tells b4 where to find patches
$ git config b4.midmask https://yhetil.org/guix-patches/%s
$ git config b4.searchmask 'https://yhetil.org/guix-patches/?x=m&t=1&q=%s'
Configure git:
$ guix shell --container --nesting --development guix --share=/var/log/guix
$ ./bootstrap
$ ./configure
$ make --jobs 24
$ echo $?
$ exit
Building takes a while.
Go make a cup of tea now!
💭
$ mkdir ~/workspace/guix-packages/worktrees
$ git worktree add ~/workspace/guix-packages/worktrees/patch-review1 \
-b patch-review1 origin/master --track
$ cd ../worktrees/patch-review1
$ guix shell --development guix --container --share=/var/log/guix --nesting --verbosity=3
[env]$ ./bootstrap
[env]$ ./configure
[env]$ make --jobs 24
[env]$ exit
Build the source just like in the main tree:
$ stg init
$ stg branch --describe "Patch reviews"
# check the branch is correctly tracking origin/master
$ stg branch --list
Initialise stgit on the worktree:
For more on StackedGit see the home page and tutorial:
Find the patch in Issues - we need the bug number and/or the message-id:
# mumi current <issue number>
$ mumi current 74131
$ mumi am
# stg uncommit --number=N
$ stg uncommit --number=1
# show the new patch
$ stg show
# b4 shazam --apply-cover-trailers <message-id>
$ b4 shazam --apply-cover-trailers \
CAM_04A3od+VxeX+mWBLNpxhR+s0w2TPqU8gm=_XQ90WYiMR-gg@mail.gmail.com
# stg uncommit --number=N
$ stg uncommit --number=1
# show the new patch
$ stg show
Create a build env and build the source:
$ guix shell --development guix --container --network --nesting --share=/var/log/guix coreutils
[build-env]$ ./pre-inst-env guix build --source --no-substitutes <package@version>
Build the package:
[build-env]$ ./pre-inst-env guix build --no-substitutes --no-grafts <package@version>
+;; There are no releases yet of this package.
+(define-public guile-uuid
+ (let ((commit "64002d74025f577e1eeea7bc51218a2c7929631f")
+ (revision "0"))
+ (package
+ (name "guile-uuid")
+ (version (git-version "0.0.0" revision commit))
+ (source
+ (origin
+ (method git-fetch)
+ (uri (git-reference
+ (url "https://codeberg.org/elb/guile-uuid.git")
+ (commit commit)))
+ (file-name (git-file-name name version))
+ (sha256
+ (base32 "1q6dqm2hzq75aa5mrrwgqdml864pdrxc98j7pyj1y0827phnzjfj"))))
Use stg show to see the patch:
Example of checking Pypi:
[dev-env]$ wget \
https://files.pythonhosted.org/packages/0a/c5/b7237226724951d7aad79dc24d49b661e5aaad671b43f076beb6f6a4e647/ \
borgmatic-1.8.14.tar.gz
[dev-env]$ guix hash --hash=sha256 --format=hex borgmatic-1.8.14.tar.gz
598b3bc22c19d53bd375e5295afec56d111759f74671845aacfe055c539fa746
Pypi page for this release confirms the hash:
Checking the guile-uuid package:
$ cd /tmp
$ guix download --git --commit=64002d74025f577e1eeea7bc51218a2c7929631f https://codeberg.org/elb/guile-uuid.git
/gnu/store/bwpfya9s462mwvf07kd0q4xswxa6jy6x-guile-uuid-64002d7
1q6dqm2hzq75aa5mrrwgqdml864pdrxc98j7pyj1y0827phnzjfj
Matches the one in the package definition in stg show:
+ (sha256
+ (base32 "1q6dqm2hzq75aa5mrrwgqdml864pdrxc98j7pyj1y0827phnzjfj"))))
Create a test-env environment:
$ guix shell --development guix --container --network --nesting --expose=/etc/ssl coreutils nss-certs man-db
[test-env]$ ./pre-inst-env guix package --install guile guile-readline guile-colorized <package>
[test-env]$ GUIX_PROFILE="/home/steve/.guix-profile"
[test-env]$ . "$GUIX_PROFILE/etc/profile"
Use the Guile REPL to test the module:
# start a guile repl
[test-env]$ guile
;;; import the module using whatever path the library tells you about
=> ,import (uuid generate)
=> (generate-string-uuid)
Create a test-env environment and check the source:
Build the package as well:
$ guix shell --development guix --container --network --nesting --share=/var/log/guix coreutils
[build-env]$ ./pre-inst-env guix build --source --no-substitutes <package@version> --check
[build-env]$ ./pre-inst-env guix build --no-substitutes --no-grafts <package@version> --check
Format the code in the dev env:
[dev-env]$ emacs -nw gnu/packages/backup.scm
Run the styler in the test env:
[test-env]$ ./pre-inst-env guix style --dry-run borgmatic@1.8.14
[test-env]$ ./pre-inst-env guix lint --dry-run borgmatic@1.8.14
Run the linter in the test env:
Check the patches contents are correct:
1. Package Synopsis and Description are adequate: some maintainers want factual text (a bit subjective!). Guix lint checks things like spacing and no use of definitive article.
2. Licenses in the package match those of the source. Check against the projects source code. Note that MIT license is called the Expat license.
2. Running Guix lint will show common problems
Check the patches works
1. We checked that the package's source is downloading correctly in step XX
2. We checked the package build correctly in step XX
2. The package must build deterministically - checked in step NN
Check the patches code is correct.
1. Check the package's source (origin) doesn't have bundled libraries. Vendored libraries are not acceptable.
2. Each patch contains one discrete change. This is often interpreted to mean a change to only one package.
3. Is the code formatted in a way that's similar to other code around it. Guix style will often change code - this should be done in a separate commit to make reviews easy.
4. Package changes are often uncontroversial except for if they impact large numbers of other packages. Contributors often miss this!
5. Good use of Guix modules/functions is a bit subjective, but generally it's things like using Gexps
6. The commit message format will almost certainly be wrong!
In the dev env create a new StackedGit patch:
[dev-env]$ stg new borgmatic-1.8.14
Create a commit message - there's a set format:
gnu: borgmatic: Update to 1.8.14.
* gnu/packages/backup.scm (borgmatic): Update to 1.8.14.
Add the changes we've made into the patch:
[dev-env]$ stg refresh gnu/packages/backup.scm
[dev-env]$ stg series --reverse --description
[dev-env]$ stg show
In the test env check for dependants:
[test-env]$ ./pre-inst-env guix refresh --list-dependent borgmatic@1.8.14
No dependents other than itself: borgmatic@1.8.14
https://guix.gnu.org/manual/en/html_node/Submitting-Patches.html
Check if there are any changes in the dev env:
[dev-env]$ stg status
Do a diff:
[dev env]$ stg diff
[dev-env]$ stg refresh gnu/packages/backup.scm
[dev-env]$ stg show
If there are changes update the patch:
Start a shell in the dev env:
[dev-env]$ guix shell --development guix guile git:send-email stgit@2.4.0 debian-devscripts-bts
[dev-env]$ export PS1='[email-env]$ '
# email passwords are locked - I use keychain
[email-env] keychain --agents ssh,gpg
Use stg email format in the email env:
[email-env]$ stg email format --output-directory ../stg-out --numbered --base=auto --thread=shallow \
--cover-letter --all
[email-env]$ vim ../stg-out/0000-cover-letter.patch
Edit the cover letter email:
Get the base commit from the cover letter:
[email-env]$ view ~/workspace/guix-packages/worktrees/stg-out/0000-cover-letter.patch
Create a new branch:
[email-env]$ cd ~/workspace/guix-packages/guix
[email-env]$ stg branch --list
[email-env]$ stg branch master
[email-env]$ git branch borgmatic-test-apply <base-commit-from-cover-letter>
[email-env]$ git switch borgmatic-test-apply
[email-env]$ git log
[email-env]$ git am --ignore-whitespace --ignore-space-change --no-scissors
~/workspace/guix-packages/worktrees/stg-out/0001-*
[email-env]$ git log
[email-env]$ git log --patch
Apply the patch:
Run the etc/teams.scm get-maintainer command:
[email-env]$ cd ~/workspace/guix-packages/guix/worktrees/borgmatic-1.8.14
[email-env]$ ./pre-inst-env etc/teams.scm get-maintainer \
~/workspace/guix-packages/worktrees/stg-out/0001-gnu-borgmatic-Update-to-1.8.14.patch
# check it ran correctly as it doesn't output anything if there's no applicable maintainer
[email-env]$ echo $?
Other useful commands:
# list all the teams
[email-env]$ ./pre-inst-env list-team #list all teams
# print the cc's for any team (e.g. rust)
[email-env]$ ./pre-inst-env etc/teams.scm cc rust
Send the cover-letter:
[email-env]$ git send-email --to=guix-patches@gnu.org --annotate --dry-run 0000-cover-letter.patch
# now rm the cover letter so there's no chance it's sent again!
[editor-split] rm 0000-cover-letter.patch
To add a Maintainer:
[editor-split]$ git send-email --to=guix-patches@gnu.org --cc="Some Person <maintainer@some.email>"
--annotate --dry-run 0000-cover-letter.patch
Use bts to query the bug number:
[email-env]$ bts --bts-server https://debbugs.gnu.org/ --mbox show NNNN
Re-export the patches with the reply-to header set to the Message-ID:
[email-env]$ rm ~/workspace/guix-packages/worktrees/stg-out/*
[email-env]$ stg email format --output-directory ../stg-out --numbered --base=auto
--add-header="X-Debbugs-Cc: Jane Maintainer <jane@maintainer.email>, Bob Maintainer <bob@maintainer.email>"
--to NNNN@debbugs.gnu.org --in-reply-to <message-id-we-grabbed> --thread=shallow --all
[email-env]$ git send-email --to=NNNN@debbugs.gnu.org --no-thread --no-chain-reply-to
--dry-run ../stg-out/*
Send the patch with:
An example of a re-roll:
[email-env]$ stg email format --output-directory ../stg-out --numbered --base=auto \
--to NNNN@debbugs.gnu.org --in-reply-to <original-cover-letter-message-id> --thread=shallow \
--cover-letter
--reroll-count=2
--all
Delete the worktree and the git branch:
$ cd ~/workspace/guix-packages/guix
$ git worktree list
$ git worktree remove ~/workspace/guix-packages/worktrees/test-borgmatic-1.8.14
$ stg branch --list
$ stg branch --delete borgmatic-1.8.14
Altering a package is pretty simple
Quite involved ... but tools like worktrees and StackedGit can help
Meeting all the quality standards is a lot of steps and we need patience!
To learn more:
Next steps from here:
In the dev env:
[dev-env]$ cd ~/workspace/guix-packages/worktrees/borgmatic-1.8.14
[dev-env]$ vim gnu/packages/backup.scm
(define-public borgmatic
(package
(name "borgmatic")
(version "1.8.14")
(source
(origin
(method url-fetch)
(uri (pypi-uri "borgmatic" version))
(sha256
(base32 "0im7kx9mq1gymid88wa6yxcif4bdqpz5lag5fp9kpm8r5k13p2sr"))))
[... rest of the package definition ...]
Change the package definition:
change the version
use the hash
Create build env in a Tmux split:
$ guix shell --development guix --container --network --nesting --preserve=^TERM$
coreutils nss-certs man-db ncurses
export PS1='[test-env]$ '
Create test env in a Tmux split:
$ guix shell --development guix --container --network --nesting --share=/var/log/guix
--preserve=^TERM$ coreutils
$ export PS1='[build-env]$ '
Another Tmux split for using an editor - not in guix shell:
$ export PS1='[dev-env]$ '
ensures guix build writes logs
installs all package inputs
installs packages for guix lint (nss-certs) and testing
Create a guix shell to build the source in:
[env]$ ./bootstrap
[env]$ ./configure --localstatedir=/var --sysconfdir=/etc
[env]$ make
[env]$ exit
Bootstrap, configure and build the guix source:
$ cd ~/workspace/guix-packages/worktrees/borgmatic-1.8.14
$ guix shell --container --nesting --development guix --pure
--manifest=../../scm/guix-dev-env.scm --verbosity=3
Manifest has some basic tools:
(specifications->manifest (list "glibc-locales" "gcc-toolchain" "autoconf" "automake" "texinfo"
"coreutils" "inetutils" "findutils" "which" "lesspipe" "help2man"
"git" "strace"))
2:40 minutes