From d6ccbeedbd8418a5f4eaa78ef24b19b9f43cb4a8 Mon Sep 17 00:00:00 2001
From: Shea Levy <shea@shealevy.com>
Date: Mon, 31 Oct 2016 18:17:17 +0100
Subject: [PATCH] doc: add basic docs about declarative projects

Conversion of Shea's *.md, added as a subsection.  Shea is left as author.
I made this new bit a separate file, though it might be questionable.
---
 doc/manual/declarative-projects.xml | 96 +++++++++++++++++++++++++++++
 doc/manual/projects.xml             |  2 +
 2 files changed, 98 insertions(+)
 create mode 100644 doc/manual/declarative-projects.xml

diff --git a/doc/manual/declarative-projects.xml b/doc/manual/declarative-projects.xml
new file mode 100644
index 00000000..1c9e76c1
--- /dev/null
+++ b/doc/manual/declarative-projects.xml
@@ -0,0 +1,96 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-declarative-projects">
+
+  <title>Declarative projects</title>
+  <para>
+    Hydra also supports declarative projects, where jobsets are generated
+    and configured automatically from specification files instead of being
+    managed through the UI. A jobset specification is a JSON object
+    containing the configuration of the jobset, for example:
+  </para>
+  <programlisting language="json">
+    {
+        "enabled": 1,
+        "hidden": false,
+        "description": "js",
+        "nixexprinput": "src",
+        "nixexprpath": "release.nix",
+        "checkinterval": 300,
+        "schedulingshares": 100,
+        "enableemail": false,
+        "emailoverride": "",
+        "keepnr": 3,
+        "inputs": {
+            "src": { "type": "git", "value": "git://github.com/shlevy/declarative-hydra-example.git", "emailresponsible": false },
+            "nixpkgs": { "type": "git", "value": "git://github.com/NixOS/nixpkgs.git release-16.03", "emailresponsible": false }
+        }
+    }
+  </programlisting>
+  <para>
+    To configure a declarative project, take the following steps:
+  </para>
+  <orderedlist numeration="arabic" spacing="compact">
+    <listitem>
+      <para>
+        Create a jobset repository in the normal way (e.g. a git repo with
+        a <literal>release.nix</literal> file, any other needed helper
+        files, and taking any kind of hydra input), but without adding it
+        to the UI. The nix expression of this repository should contain a
+        single job, named <literal>jobsets</literal>. The output of the
+        <literal>jobsets</literal> job should be a JSON file containing an
+        object of jobset specifications. Each member of the object will
+        become a jobset of the project, configured by the corresponding
+        jobset specification.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        In some hydra-fetchable source (potentially, but not necessarily,
+        the same repo you created in step 1), create a JSON file
+        containing a jobset specification that points to the jobset
+        repository you created in the first step, specifying any needed
+        inputs (e.g. nixpkgs) as necessary.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        In the project creation/edit page, set declarative input type,
+        declarative input value, and declarative spec file to point to the
+        source and JSON file you created in step 2.
+      </para>
+    </listitem>
+  </orderedlist>
+  <para>
+    Hydra will create a special jobset named <literal>.jobsets</literal>,
+    which whenever evaluated will go through the steps above in reverse
+    order:
+  </para>
+  <orderedlist numeration="arabic" spacing="compact">
+    <listitem>
+      <para>
+        Hydra will fetch the input specified by the declarative input type
+        and value.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Hydra will use the configuration given in the declarative spec
+        file as the jobset configuration for this evaluation. In addition
+        to any inputs specified in the spec file, hydra will also pass the
+        <literal>declInput</literal> argument corresponding to the input
+        fetched in step 1.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        As normal, hydra will build the jobs specified in the jobset
+        repository, which in this case is the single
+        <literal>jobsets</literal> job. When that job completes, hydra
+        will read the created jobset specifications and create
+        corresponding jobsets in the project, disabling any jobsets that
+        used to exist but are not present in the current spec.
+      </para>
+    </listitem>
+  </orderedlist>
+</section>
diff --git a/doc/manual/projects.xml b/doc/manual/projects.xml
index 27a847a1..a8ee2b13 100644
--- a/doc/manual/projects.xml
+++ b/doc/manual/projects.xml
@@ -1,5 +1,6 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
          xml:id="chap-projects">
 
   <title>Creating and Managing Projects</title>
@@ -468,6 +469,7 @@ build_exotic =
 
   </section>
 
+  <xi:include href="declarative-projects.xml" />
 
 </chapter>