Updating Causes of Aports Failures - oils-for-unix/oils GitHub Wiki

I maintain the master list of root causes for regtest/aports failures at:

https://op.oils.pub/aports-build/published.html

How do you update causes? This doc describes how.

Updating the Source

(Refer to this commit as an example)

For example, you can associate bug #2339 with with a string, using this statement:

patterns["#2339"] = "requires a signal or hook name"

This will "grep" each package build log for a string. If the string appears, then the package failure is assigned this root cause.

Test Locally

Suppose you built packages with aports-run.sh. Then you will have _tmp/aports-report/$APORTS_EPOCH locally, and you can test it like this:

 $ regtest/aports-html.sh write-all-reports _tmp/aports-report/2025-08-07-fix/

An even faster way:

 $ regtest/aports-html.sh merge-diffs _tmp/aports-report/2025-08-07-fix/

Retrieve Latest Results for Testing

But most people will not have run a package build locally. Then you don't have _tmp/aports-report/$APORTS_EPOCH

In this case, you will sync results from the server, extract them, and re-run the report:

First change EDITING_APORTS_EPOCH in regtest/aports-html.sh to something like 2025-08-26-ifs.wwz

Then sync this old report from the op.oils.pub web server:

$ regtest/aports-html.sh sync-old-wwz  # 2025-08-26-ifs.wwz is optional

Then extract it to a new "epoch":

$ regtest/aports-html.sh extract-old-wwz 2025-09-06-edit

Then re-generate HTML with one of these commands:

$ regtest/aports-html.sh write-all-reports _tmp/aports-report/2025-09-06-edit
$ regtest/aports-html.sh write-disagree-reports _tmp/aports-report/2025-09-06-edit

That is, write-disagree-reports is for partial runs.

You can now iterate on cause.awk, generating new HTML.

If you quickly want to test out your pattern, you can manually run grep to test it out. For example:

$ cat _tmp/aports-report/2025-10-27-edit/disagree-2025-10-15-main/osh-as-sh/log/mdev-conf.log.txt \
| grep -e "readlink disk/by-label/EFI\x20System" 
grep: warning: stray \ before x # this pattern contains a mistake
$ cat _tmp/aports-report/2025-10-27-edit/disagree-2025-10-15-main/osh-as-sh/log/mdev-conf.log.txt \
| grep -e "readlink disk/by-label/EFI" 
Executing command [ readlink disk/by-label/EFI\x20System ] # this pattern works

Redeploy

Edit the function regtest/aports-html.sh published-html to include a link to 2025-09-06-edit.

Then do:

$ regtest/aports-html.sh make-wwz _tmp/aports-report/2025-09-06-edit  # creates .wwz file

$ regtest/aports-html.sh deploy-wwz-op _tmp/aports-report/2025-09-06-edit.wwz  # upload it

Now look at:

https://op.oils.pub/aports-build/published.html