Intro to Guix Patch Reviews

Reviewing patches from contributors to help Guix

Guix Patch Review

Guix receives many contributions such as new packages and services, or updates to existing ones.
Each contribution ("patch") has to be reviewed to make sure that it works correctly and meets the projects standards
Anyone can take part in patch reviews
Doing patch reviews helps the project by:
- helping contributors by showing them where they can improve a patch
- helping committers avoid spending time on patches that aren't ready yet
- helping yourself by learning about different parts of Guix!
Learn more about the patch review process here:

https://libreplanet.org/wiki/Group:Guix/GuixSocial

Patch Review Levels

Submission review

Functionality review

Code review

Check the patches contents are correct:

Commit message correctness
Package description and synopsis correctness
License matches package definition
Patch applies correctly
Guix lint passes

Check the patches works

Does it build?
Is the build deterministic?
Does it install correctly?

Check the patches code is correct.

Is the code formatted in a way that's similar to other code?
Does the change make sense?
Does it use Guix modules and functions correctly?

Learning Path

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

Learning Path

Manifests

Transforms in Manifests

https://www.futurile.net/resources/guix/

1

Build Guix from source

3

Send the updated package

Guix Patch Review

2

Alter the package we want to change

1

Build Guix from source

23

A series of

manual steps

Modified Package Contribution in 3 Easy Steps

2

Alter the package we want to change and verify to project standards

3

Send the updated package as a patch by email

1

Build Guix from source

23

A series of involved

manual steps

Modified Package Contribution in 3 23 Easy involved Steps 😰

2

Alter the package we want to change and verify to project standards

3

Send the updated package as a patch by email

Pre-requisites

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

1. Relax before reviewing 🧘

Patch review is fun and a great way to learn about various parts of the system
It also requires a constructive state of mind:
- Contributors often find it difficult to send contributions that follow the rules correctly
- As a reviewer it can be annoying seeing the same mistakes multiple times
Try to be nice and polite to contributors - we're all learning!

https://debbugs.gnu.org/Packages.html

2a. Choose something to review

The QA system automatically builds new patches that are sent
- Look for patches that are of interest to you
- Check their status in the QA pages

Look through issues / bug-tracker
- Guix uses GNU Projects shared Debbugs
- Two Web interfaces - uses Guix Issues for simplicity

https://qa.guix.gnu.org/patches

https://issues.guix.gnu.org

https://debbugs.gnu.org/cgi/pkgreport.cgi?package=guix-patches

2a. Choose something to review

Some useful reports that show available patches
Guix Social keeps a list of reviews that may be easy to start with (usertag patch-review-hackers-list):

Easy issues (tag easy)

https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=patch-review-hackers-list;status=open;users=guix

https://issues.guix.gnu.org/forgotten

https://issues.guix.gnu.org/easy

Forgotten issues (modified over 30 days ago)

3. Preflight checks

Check whether Guix QA processed the patch
- gives insight into whether there are problem
- go to: https://qa.guix.gnu.org/issues/NNNN
Search Guix Issues to make sure there's not an existing patch being done
- Sometimes people send the same package update
For existing packages check how complex it will be

$ guix refresh --list-dependent <package>

If a package is used by many others then it's likely to be difficult to update and may not be worth reviewing if you're just getting started!

4. Set yourself as reviewer

Bugs in Debbugs can have an owner
- Every email sent to the bug will also go to the owner
- It's one way to indicate that you're working on reviewing it
Send email:
- to: control@debbugs.gnu.org
- subject: <anything you want>
- owner NNNN !
- quit
The control address is an email bot
Replace NNNN with the bug number you have
The exclamation mark is a shorthand for 'me'
- e.g. owner 1234 me

5a. Clone and build Guix

# 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

If you haven't previously cloned and build Guix this is how to.

Git clone the Guix archive:

Build the source:

5b. Configure git

$ 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 and some other tools settings on the repo

Configure git:

5c. Build guix

$ guix shell --container --nesting --development guix --share=/var/log/guix 

$ ./bootstrap
$ ./configure
$ make --jobs 24

$ echo $?
$ exit

Build the main Guix repository

1. Build in a guix shell using the container option to guarantee that it's separated from the rest of the environment. To see the build logs share /var/log/guix
3. bootstrap and configure scripts only has to be run once
7. Check that the build was successful by looking at the exit code (it normally prints an error anyway)
8. If it's successful you can exit from guix shell environment

Building takes a while.

Go make a cup of tea now!

💭

5d. Create a new worktree

Using git worktrees allows us to work on more than one package at a time - this part is optional
They allow parallel checkouts of different branches at the same time
All work is done in the worktree - by doing this I can review multiple packages at the same time - or review some for master and others for a team branch

$ mkdir ~/workspace/guix-packages/worktrees
$ git worktree add ~/workspace/guix-packages/worktrees/patch-review1 \
    -b patch-review1 origin/master --track
    
$ cd ../worktrees/patch-review1

1. all worktrees are in the same place
2. creates a worktree called patch-review1, and a branch at the same time also called patch-review1. Sets it to track origin/master

$ 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:

5e. Initialise StackedGit

StackedGit (stgit) makes git commits feel like patches
All patches are in a stack and can be moved up and down within it

$ stg init
$ stg branch --describe "Patch reviews"

# check the branch is correctly tracking origin/master
$ stg branch --list

Initialise stgit on the worktree:

all StackedGit commands are stg <something>
there are some convenience commands like stg branch
see stg --help for more

https://stacked-git.github.io/

For more on StackedGit see the home page and tutorial:

6a. Import and apply the patch

Import the patch from the bug tracker
Apply the patch to the tree
This is a single patch, sometimes it may be a series of patches
Two options are mumi or b4

Find the patch in Issues - we need the bug number and/or the message-id:

6a. Import and apply the patch

Mumi is a tool from the Guix community - it's really easy to use
It downloads & apply patches from Guix Issues - if Mumi errors switch to b4
It uses the bug number from the Issues site
Install it: guix package --install mumi

# mumi current <issue number>
$ mumi current 74131
$ mumi am

The mumi current command sets the bug number from Issues that Mumi is on
To print the current bug it's on do mumi current
To change to a different one do mumi new and then mumi current <issue number>

# stg uncommit --number=N
$ stg uncommit --number=1

# show the new patch
$ stg show

After the mumi current we have a new commit in the tree
We pull it into our StackedGit (stg) stack of patches so we can manipulate it
Sometimes stg will tell you that the git metadata and it's metadata are now not in sync and to run stg repair - this is safe

6b. Import and apply the patch

b4 is a tool from the Linux kernel community - powerful but complex
It can download and apply patches from mailing lists - and much more
It uses the Message-id from Guix Issues to apply the patch
Install it: guix package --install b4

# b4 shazam --apply-cover-trailers <message-id>
$ b4 shazam --apply-cover-trailers \
      CAM_04A3od+VxeX+mWBLNpxhR+s0w2TPqU8gm=_XQ90WYiMR-gg@mail.gmail.com

The b4 shazam command downloads the patch and applies it
Uses the message-id - which we got from Guix Issues
we defined the public-inbox to use when we set git config earlier

# stg uncommit --number=N
$ stg uncommit --number=1

# show the new patch
$ stg show

After the b4 shazam we have a new commit in the tree
We pull it into our StackedGit (stg) stack of patches so we can manipulate it
Sometimes stg will tell you that the git metadata and it's own metadata are now not in sync and to run stg repair - this is safe

7. Build the patched package

Check the source downloads correctly
Build the package: it needs to build correctly using with the new patch

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>

Using --no-substitutes prevents downloading the binary substitute from Guix
Using --no-grafts for development builds makes builds faster - a final test build without this option is needed - as grafts provide security updates

Guix shell container guarantees a separated environment. The nesting option is so commands can be send to the guix daemon
Access to the build log from guix shell --container requires sharing /var/log/guix
The guix build --source command downloads the source code from the origin - it will show an error if the version or hash is wrong.
Using --no-substitutes prevents it downloading the source form Guix's servers

8a. Calculate the hash

Source files use hashes and signatures to prevent MITM attacks
We check:
- (a) if it's an upstream release archive (url-fetch) that the files match what the upstream maintainer released
- (b) the hash Guix is using matches the source

+;; 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"))))

3. There are no releases, so there's no signed archive.
10. We're downloading the source from git - (method git-fetch)
16. Guix acalculates a SHA256 hash of that download - we can check that's correct

Use stg show to see the patch:

8b. Upstream hash example

Different source locations (origin) require different checking
Pypi provides hashes in hexadecimal that we can check
Guix hash command calculates a hash of a source

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:

8c. Package hash example

Each package has a SHA256 hash of the source files - prevents MITM attacks
The guix hash command is used
Guix uses the format nix-base32 for its own package source hashes

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

The guix hash command will work with a file or a git repository
Confirms that the git source and the package's source match
As long as no-one's tampered with the source in Git we're in good shape!

Matches the one in the package definition in stg show:

+       (sha256
+        (base32 "1q6dqm2hzq75aa5mrrwgqdml864pdrxc98j7pyj1y0827phnzjfj"))))

9a. Test install the package

Building the package doesn't mean it's working - install and test it!
Testing a package will depend on what sort it is - learn as you go along!

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)

Standard CLI utilities can be run in a test environment
Graphical applications are a bit more difficult
Libraries for dynamic languages like Guile, Ruby, Python are often testable using their REPL
Other libraries may not be manually testable (e.g. Go, Rust)

10. Test build determinism

The package builds and it works
This test is whether builds are reproducible
The guix build command has a --check option that does this.

Create a test-env environment and check the source:

Build the package as well:

The --check option will build the package again and then check if the hash is the same
There has to be an existing build of the package for this to work - otherwise build the package using the normal options - then build again using --check

$ 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

15. Check the formatting

Formatting the code with Emacs (I know) is the easiest way for changes to meet the "expected style" that maintainers will check
For Vim users Spacemacs is great - highlight the code and use :indent-region
Packages can use guix style for standardised formatting - many older ones don't use this style - decide how intrusive you want to be
Use guix lint to check that a package meets packaging standards and that there are no known security issues

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:

Level 1: Submission Review

Check the patches contents are correct:

Package description and synopsis correctness
License matches package definition
Patch applies correctly
Guix lint passes
Commit message correctness

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

Quickly submit a review on Guix's QA site
As it's a quick Web page it doesn't include a "Reviewed-by" patch trailer
Say what you checked so everyone knows
The review appears on the Guix Issue page

QA Review Page

Level 2 : Functionality Review

Check the patches works

Does it build?
Is the build deterministic?
Does it install correctly?
Does it work?

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

Quickly submit a review on Guix's QA site
As it's a quick Web page it doesn't include a "Reviewed-by" patch trailer
May also want to submit it as an updated (re-roll) patch
The review appears on the Guix Issue page

Level 3: Code Review

Check the patches code is correct.

Is the code formatted in a way that's similar to other code?
Does the change make sense?
Does it use Guix modules and functions correctly?

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!

16. Check list for contribution

Each patch contains one discrete change only: changes to one package
Package source has no bundled libraries (e.g. vendored libraries)
Verify the source and ensure the Package hash is correct (Step 8)
Package builds correctly (Step 10 & 12): check the source is downloading and that it builds deterministically
Package works (Step 11): test it in a guix shell
Package builds on other architectures: Guix's CI does this
Patch commit message meets the standard (Step 13): look at previous commit messages
Package only references other packages it needs (Step 14): also guix size
Package is styled correctly (Step 15): guix style
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
Package passes lint (Step 15): guix lint
Patch goes to the topic branch of a team if possible: e.g. rust-team or python-team
Packages for the master branch don't involve substantial rebuilds: new branch potentially

https://guix.gnu.org/manual/en/html_node/Submitting-Patches.html

13. Create the patch (using stg)

StackedGit lets us treat a commit as a patch
We see the same patch we'll eventually send to the Guix developers

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.

To create a new patch in a series: stg new (each patch is one git commit)
To add changes from the working tree into the patch: stg refresh <path>
To show the contents of the current patch: stg show
To see the series of patches (commits): stg series --reverse --description
Other commands to move patches in the stack, and to pull in commits

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

14. Check for dependant packages

If there are dependant packages they need to be rebuilt to make sure everything works
We tested this earlier with guix graph
Alternative way is to use guix refresh

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

Recommended as part of Submitting Patches section:

https://guix.gnu.org/manual/en/html_node/Submitting-Patches.html

The guix refresh command is great for finding packages that need updates

17. Update the patch

Update the patch with any changes
Diff between working copy and commit: stg diff
Update the patch: stg refresh <path>
Show the current patch: stg show

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:

18. Export patches & test apply (pt 1)

Format the patch as an email and test it by applying it to a new branch
Format the patch for email: stg email format
Specific to my set-up is my email passwords are locked inside GPG: keychain

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:

stg email format: --output-directory <dir> - where the patches are placed - in ../stg-out directory
stg email format: --numbered will number the patch files and in the Subject
stg email format: --base=auto
stg email format: --thread=shallow - all subsequent emails are a reply to the cover letter
stg email format: --cover-letter - create a cover letter (which needs to be edited)
stg email-format: --all means the entire stack, can also use 1..4 to export part of a stack

18. Export patches & test apply (pt 2)

Check the patches cleanly apply on a new branch
List branches with: stg branch --list
Apply the patch: git am

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:

git am: maximise applying with --ignore-whitespace and --ignore-space-change
git am: ignore scissors

19. Check for CC's

If there is an active Maintainer for a package a patch is more likely to be reviewed
There are some teams that look after whole package areas e.g. python-team
The Guix source has some git settings (etc/git) which will automatically cc teams when using git send-email if we're within the source tree
We have to manually add them as CC's when sending a cover-letter

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

20. Create a new bug

If we send multiple emails to the bug tracker (debbugs) it will create multiple bugs. When we want a single bug with multiple patches attached to it.
To avoid this - send the cover letter to guix-patches mailing list first - this email list is watched by the bug tracker and it will create a new bug number
CC any Maintainer that we discovered earlier so they're included
Then send the patch(es) to this bug number so they're all grouped correctly

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

git send-email: use cc=<email> not X-Debbugs-cc for the cover letter as this is going to the mail list, not directly to Debbugs

git send-email: uses options that we added using stg email format (e.g. threading)
git send-email: --annotate will open up the email in an editor
git send-email: --dry-run takes no action but shows what it would have done

21. Thread & send the patches

Debbugs replies with an email specifying the new bug number
So the patch(es) are threaded as replies to the cover-letter we use the cover letters' Message-ID when we send the rest of the patches
To get the Message-ID use the Guix Issues site or the bts tool
The python-apprise patch is within a file that python-team focuses on. Guix's git config will automatically send this patch to them. The other is not - if we want the series to go to the python team we need to manually add them using X-Debbugs-CC special header

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:

22. Check patches pass QA

Check the patches successfully go to the bug-tracker
- https://issues.guix.gnu.org/NNNN
- or: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=NNNN
The QA system builds every patch that it sees
- https://qa.guix.gnu.org/issue/NNNN
Builds can take a while: https://qa.guix.gnu.org/patches
Re-roll the patch if there is feedback or to re-trigger QA

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

stg email format: --reroll-count=N marks the series as the n-th iteration of the topic. So the first time we send the patch series it's 1st time, if we need to re-roll the count starts at 2.

Send the patches directly to the bug number - no need to CC as debbugs will automatically do this due to the X-Debbugs-Cc header that was used earlier

23. Close the branch when complete

Waiting for someone to review and apply your patch is hard - and who knows when someone will look at it!
Make sure it passes QA so that it's easy for a Maintainer to apply
If no-one is looking at it after a few weeks try asking on IRC
Generally the maintainer will email to the bug confirming when it's applied - delete the worktree and branch when it's in the archive

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

What we've seen 🎉

Altering a package is pretty simple

1 Modifying packages

Quite involved ... but tools like worktrees and StackedGit can help

2..

Contributing changes

Meeting all the quality standards is a lot of steps and we need patience!

..23

Quality!

Taking it further

To learn more:

Futurile blog: https://www.futurile.net/resources/guix
Guix Manual: https://guix.gnu.org
Come along to the Guix.social online meet-up!

Next steps from here:

More complex modifications of packages and services
Add new packages to Guix
Run a channel with our own packages

Thank You!

9. Update the package definition

Use guix edit borgmatic to discover which file the package definition is in
Edit the package in your favourite editor - Vim of course!

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

7. Create packaging envs

For packaging need multiple separate terminal environments:
- build: guix shell env with development guix
- test: guix shell env with development guix and testing packages
- dev & hash: normal environment to run code editor guix hash in
I use Tmux with four separate splits so I can have them all on the screen easily

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

6. Build the Guix source

Build the source that's in the worktree

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:

building will take a while!
if it's successful exit from the environment

(specifications->manifest (list "glibc-locales" "gcc-toolchain" "autoconf" "automake" "texinfo"
                                "coreutils" "inetutils" "findutils" "which" "lesspipe" "help2man"
                                "git" "strace"))

VIDEO

Guix Build

2:40 minutes

Guix Package Patch Reviews

By futurile

Guix Package Patch Reviews

How to update a Guix package and contribute the new version to the main Guix repository

Intro to Guix Patch Reviews

Guix Patch Review

Patch Review Levels

Learning Path

Learning Path

1

3

Guix Patch Review

2

1

23

Modified Package Contribution in 3 Easy Steps

2

3

1

23

Modified Package Contribution in 3 23 Easy involved Steps 😰

2

3

Pre-requisites

1. Relax before reviewing 🧘

2a. Choose something to review

2a. Choose something to review

3. Preflight checks

4. Set yourself as reviewer

5a. Clone and build Guix

5b. Configure git

5c. Build guix

5d. Create a new worktree

5e. Initialise StackedGit

6a. Import and apply the patch

6a. Import and apply the patch

6b. Import and apply the patch

7. Build the patched package

8a. Calculate the hash

8b. Upstream hash example

8c. Package hash example

9a. Test install the package

10. Test build determinism

15. Check the formatting

Level 1: Submission Review

QA Review Page

Level 2 : Functionality Review

Level 3: Code Review

16. Check list for contribution

13. Create the patch (using stg)

14. Check for dependant packages

17. Update the patch

18. Export patches & test apply (pt 1)

18. Export patches & test apply (pt 2)

19. Check for CC's

20. Create a new bug

21. Thread & send the patches

22. Check patches pass QA

23. Close the branch when complete

What we've seen 🎉

1

Modifying packages

2..

Contributing changes

..23

Quality!

Taking it further

Thank You!

9. Update the package definition

7. Create packaging envs

6. Build the Guix source

VIDEO

Guix Build

Guix Package Patch Reviews

More from futurile