Re: GSoC: Adding a web interface similar to the Hydra web interface

[Ricardo Wurmus <rekado@elephly.net>]

Hi Tatiana,

> Yes, I've taken a look at Hydra. I think my problem is that I don't totally
> understand what means some pages at Hydra and how it is related to Cuirass
> database tables. Hydra has Projects, Jobsets for each project, Evaluations
> and Jobs for each Jobset. And Cuirass has Specifications, Evaluations and
> Derivations. Could you please clarify how these entities are related to
> each other?

This is a good question and I can relate to your confusion about these
terms :)

A Cuirass “Specification” roughly combines what Hydra calls a “Project”
with a “Jobset”.  On Hydra you would have a Project “gnu” (arbitrary
name) with a Jobset for building all packages from the “master” branch,
and another Jobset for building all packages from the “core-updates”
branch.  A Cuirass specification looks something like this (taken from
the manual):

--8<---------------cut here---------------start------------->8---
 `((#:name . "hello")
   (#:url . "git://git.savannah.gnu.org/guix.git")
   (#:branch . "master")
   (#:no-compile? . #t)
   (#:load-path . ".")
   (#:proc . cuirass-jobs)
   (#:file . "/tmp/drv-file.scm")
   (#:arguments (subset . "hello")))
--8<---------------cut here---------------end--------------->8---

As you can see it includes a name and the repository URL (~= “Project”),
as well as the branch and a procedure “proc” that specifies how this is
to be built.

Evaluations in Hydra and Cuirass are the same concept.  The Cuirass
manual says:

    An evaluation relates a specification with the revision of the
    repository specified therein.  Derivations and builds (see below)
    each belong to a specific evaluation.

When an evaluation is started, we take a look at the current state of
the repository and then determine all build processes that need to be
performed.

Derivations are a fundamental concept in Guix.  The Guix manual says
this about derivations:

--8<---------------cut here---------------start------------->8---
Low-level build actions and the environment in which they are performed
are represented by “derivations”.  A derivation contains the following
pieces of information:

   • The outputs of the derivation—derivations produce at least one file
     or directory in the store, but may produce more.

   • The inputs of the derivations, which may be other derivations or
     plain files in the store (patches, build scripts, etc.)

   • The system type targeted by the derivation—e.g., ‘x86_64-linux’.

   • The file name of a build script in the store, along with the
     arguments to be passed.

   • A list of environment variables to be defined.

   Derivations allow clients of the daemon to communicate build actions
to the store.
--8<---------------cut here---------------end--------------->8---

When the build actions that are prescribed by a derivation are
performed, the result is a build.  This could be a failed build or a
directory containing the files that were generated by compiling a
package.

In the Hydra web interface “derivations” are not mentioned; instead they
speak of “Jobs”, which is roughly the same thing.  After all, a
derivation needs to be processed to get a build, so we can consider the
collection of derivations in a particular evaluation of a specification
to be a collection of build jobs.

> I have come up with the following list of features: […]

The list looks very good.  Please see my comments below.

> 1. Add the list of all evaluations of a specification displaying numbers of
> successful and failed builds for each evaluation (like this list
> https://hydra.nixos.org/jobset/gnu/guile-2-0/evals).

Just a note: The example URL you picked may be a little misleading
because hydra.nixos.org is used slightly differently from hydra.gnu.org
— for our specifications the number of successful, failed, and ongoing
builds would be considerably larger than in this example.

This would be a very useful feature, because we could observe a trend:
as the repository is changed and an increasing number of evaluations are
completed, do more builds fail now than before, or are we improving…?

Clicking on the number of failed/successful/pending builds we should get
a list of those builds/derivations.

> 2. Add the table with status information of each job-evaluation pair like
> https://hydra.nixos.org/jobset/gnu/guile-2-0/#tabs-jobs.

A table like this would be very large, because in our case evaluations
result in thousands of derivations (= jobs).  So you need to design this
to use pagination.

With a very long table, collecting all this past information (on the
columns) can be expensive, so I’d suggest to only display the *current*
state, not the state over a range of past days.

> Am I right that
> in terms of Cuirass database derivations correspond to jobs?

Correct.

> So, we need to
> display "derivations" table with derivations as rows and evaluations as
> columns and fill the cells using information from the "builds" table?

Correct.

> Also,
> it is not clear to me how to order evaluations by their creation time like
> it's done in Hydra.

The “Evaluations” table has an “id” field, which contains an
incrementing numeric identifier.  While you may not be able to sort them
by creation time you could sort them by “id”.

> 3. Add page displaying information about a build similar to
> https://hydra.nixos.org/build/74870692. Am I right that here we should
> display the information stored in hydra-like build description (defined
> in http.scm) alongside with links to the build log and outputs?

Correct.

Most important for us is to see the state of the build, the derivation
that corresponds to the build and the build log.

> 4. Add additional information about previous builds (latest successful,
> first broken, etc) on this build page. For this feature, we need to extend
> database requests functionality.

Yes, obtaining this information may require some new procedures in
Cuirass to perform SQL queries efficiently.

> 5. Add job information page containing the list of job's latest builds like
> https://hydra.nixos.org/job/gnu/guile-2-0/build.x86_64-linux.

Yes, this would be good.

> What do you think about these features? I afraid that I am not familiar
> with typical Hydra use cases, so I may miss some important features.

Your selection of features is very good.

What we want to know when looking at the Cuirass web interface is:

1) is the build farm building something?
2) if so, what is it building?
3) how many more things does it need to build in this round (=
   “evaluation”)?
4) has any build failed?
5) if so, how did the builds fail?
6) what build failure is blocking a certain package from being built?
7) is the percentage of failing builds decreasing over time as we modify
   the repository?
…

The Cuirass web interface should allow us to answer questions of this
kind.  The features you have selected to work on next would already be
very useful to answer some of these questions.  Good job!

--
Ricardo