From 7be84c43231c2dc59e44e4c783729d6cb4f5431b Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Thu, 30 Sep 2021 21:34:43 +0300
Subject: Add support for soft and hard rebuilds

---
 doc/manual.cli | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 93ba6f0..38b52e0 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -198,10 +198,13 @@ summary: Windows 10 build 1607 with VC 14 update 3
 id: <machine-id>
 \
 
-The uniquely machine version/revision/build identifies. For virtual machines
+The unique machine version/revision/build identifier. For virtual machines
 this can be the disk image checksum. For a container this can be UUID that is
 re-generated every time a container filesystem is altered.
 
+Note that we assume that a different machine identifier is assigned on any
+change that may affect the build result.
+
 
 \h2#arch-machine-header-name|\c{name}|
 
@@ -334,6 +337,7 @@ repository-url: <repository-url>
 [tests]: <dependency-package>
 [examples]: <dependency-package>
 [benchmarks]: <dependency-package>
+[dependency-checksum]: <checksum>
 
 machine: <machine-name>
 target: <target-triplet>
@@ -342,6 +346,7 @@ target: <target-triplet>
 [host]: true|false
 [warning-regex]: <warning-regex>
 [interactive]: <breakpoint>
+[worker-checksum]: <checksum>
 \
 
 
@@ -382,6 +387,7 @@ The repository type (see \c{repository-url} for details). Alternatively, the
 repository type can be specified as part of the URL scheme. See
 \l{bpkg-repository-types(1)} for details.
 
+
 \h2#arch-task-trust|\c{trust}|
 
 \
@@ -413,6 +419,16 @@ excluded from building due to their \c{builds}, \c{build-include}, and
 \c{build-exclude} manifest values.
 
 
+\h2#arch-task-dependency-checksum|\c{dependency-checksum}|
+
+\
+[dependency-checksum]: <checksum>
+\
+
+The package dependency checksum received as a part of the previous build task
+result (see \l{#arch-result Result Manifest}).
+
+
 \h2#arch-task-machine|\c{machine}|
 
 \
@@ -532,6 +548,16 @@ special \c{error} or \c{warning} value. See \l{#arch-worker Worker Logic} for
 details.
 
 
+\h2#arch-task-worker-checksum|\c{worker-checksum}|
+
+\
+[worker-checksum]: <checksum>
+\
+
+The worker checksum received as a part of the previous build task result (see
+\l{#arch-result Result Manifest}).
+
+
 \h#arch-result|Result Manifest|
 
 The result manifest describes a build result. The manifest synopsis is
@@ -556,6 +582,9 @@ status:                  <status>
 [install-log]:        <text>
 [test-installed-log]: <text>
 [uninstall-log]:      <text>
+
+[worker-checksum]:     <checksum>
+[dependency-checksum]: <checksum>
 \
 
 
@@ -586,6 +615,7 @@ status: <status>
 The overall (cumulative) build result status. Valid values are:
 
 \
+skip       # Package update and subsequent operations were skipped.
 success    # All operations completed successfully.
 warning    # One or more operations completed with warnings.
 error      # One or more operations completed with errors.
@@ -606,6 +636,12 @@ abnormally, for example, due to the package manager or build system crash.
 Note that the overall \c{status} value should appear before any per-operation
 \c{*-status} values.
 
+The \c{skip} status indicates that the received from the controller build task
+checksums have not changed and the task execution has therefore been skipped
+under the assumtion that it would have produced the same result. See
+\c{agent-checksum}, \c{worker-checksum}, and \c{dependency-checksum} for
+details.
+
 
 \h2#arch-result-x-status|\c{*-status}|
 
@@ -640,6 +676,26 @@ the list of supported operation names refer to the \c{*-status} value
 description.
 
 
+\h2#arch-result-dependency-checksum|\c{dependency-checksum}|
+
+\
+[dependency-checksum]: <checksum>
+\
+
+The package dependency checksum obtained as a byproduct of the package
+configuration operation. See \l{bpkg-pkg-build(1)} command's
+\c{--rebuild-checksum} option for details.
+
+
+\h2#arch-result-worker-checksum|\c{worker-checksum}|
+
+\
+[worker-checksum]: <checksum>
+\
+
+The version of the worker logic used to perform the package build task.
+
+
 \h#arch-task-req|Task Request Manifest|
 
 An agent (or controller acting as an agent) sends a task request to its
@@ -734,6 +790,7 @@ subsequent sections.
 session: <id>
 [challenge]: <text>
 [result-url]: <url>
+[agent-checksum]: <checksum>
 \
 
 
@@ -771,6 +828,16 @@ private key and then \c{base64}-encoding the result.
 The URL to POST (upload) the result request to.
 
 
+\h2#arch-task-res-agent-checksum|\c{agent-checksum}|
+
+\
+[agent-checksum]: <checksum>
+\
+
+The agent checksum received as a part of the previous build task result
+request (see \l{#arch-result-req Result Request Manifest}).
+
+
 \h#arch-result-req|Result Request Manifest|
 
 On completion of a task an agent (or controller acting as an agent) sends the
@@ -784,6 +851,7 @@ description of each value in subsequent sections.
 \
 session: <id>
 [challenge]: <text>
+[agent-checksum]: <checksum>
 \
 
 
@@ -807,6 +875,15 @@ response. It must be present only if the \c{challenge} value was present in
 the task response.
 
 
+\h2#arch-result-req-agent-checksum|\c{agent-checksum}|
+
+\
+[agent-checksum]: <checksum>
+\
+
+The version of the agent logic used to perform the package build task.
+
+
 \h#arch-worker|Worker Logic|
 
 The \c{bbot} worker builds each package in a \i{build environment} that is
-- 
cgit v1.1