01/01: doc: Add 'cuirass-howto.org'.

[Ludovic Court�s]

civodul pushed a commit to branch master
in repository maintenance.

commit 1398fe526a048a441906a08b22828ee3bf11f424
Author: Ludovic Courtès <address@hidden>
Date:   Tue Oct 15 10:17:39 2019 +0200

    doc: Add 'cuirass-howto.org'.
    
    * doc/cuirass-howto.org: New file.
---
 doc/cuirass-howto.org | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/doc/cuirass-howto.org b/doc/cuirass-howto.org
new file mode 100644
index 0000000..f559501
--- /dev/null
+++ b/doc/cuirass-howto.org
@@ -0,0 +1,64 @@
+#+TITLE: Tips and tricks on Cuirass administration
+
+This file documents tips and tricks on how to configure the Cuirass
+continuous integration tool while it’s running, for instance on
+berlin.guix.gnu.org.
+
+Most live configuration changes involve:
+
+  1. logging in on berlin.guix.gnu.org;
+  2. editing /var/lib/cuirass/cuirass.db as root.
+
+User friendliness!
+
+* Adding a new branch to build
+
+This is how you’d insert a =wip-texlive= job to build the =wip-texlive=
+branch.
+
+  #+begin_src sh
+    $ sudo sqlite3 /var/lib/cuirass/cuirass.db
+    sqlite> insert into specifications values('wip-texlive', '()', '()', 
'wip-texlive','build-aux/cuirass/gnu-system.scm', 'cuirass-jobs', '((systems 
"x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux"))');
+    sqlite> insert into inputs values('wip-texlive', 'wip-texlive', 
'https://git.savannah.gnu.org/git/guix.git', '.', 'wip-texlive', NULL, NULL, 1);
+
+  #+end_src
+
+Note that there are 3 things named =wip-texlive= here: the spec, the
+input, and the branch.
+
+* Deleting a job
+
+Here’s how you’d delete the =wip-texlive= job:
+
+  #+begin_src sh
+    sqlite> delete from inputs where name = 'wip-texlive';
+    sqlite> delete from specifications where name = 'wip-texlive';
+
+  #+end_src
+
+* Changing the =core-updates= spec to build just the “core” subset
+
+  #+begin_src sh
+    $ sudo sqlite3 /var/lib/cuirass/cuirass.db
+    SQLite version 3.26.0 2018-12-01 12:34:55
+    Enter ".help" for usage hints.
+    sqlite> update specifications set proc_args='((subset . "core")(systems 
"x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux"))' where 
name='core-updates-core-updates';
+
+  #+end_src
+
+* Canceling pending builds
+
+Support evaluation 7777 has queued lots of builds that you’d rather not
+performed, here’s how you’d cancel them:
+
+#+begin_src sh
+  $ sudo sqlite3 /var/lib/cuirass/cuirass.db
+  SQLite version 3.26.0 2018-12-01 12:34:55
+  Enter ".help" for usage hints.
+  sqlite> update builds set status=4 where evaluation=7777;
+  sqlite> 
+
+#+end_src
+
+The value 4 for =status= comes from the =build-status= enum in the
+=(cuirass database)= module.