From ee220058d977738c02ead45cc5567bbab33adf48 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Mon, 5 Aug 2024 14:14:24 +0200
Subject: Document package review manifest

---
 doc/manual.cli | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 9b85ae6..941e8f4 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -596,4 +596,74 @@ message: <string>
 [reference]: <string>
 \
 
+
+\h1#package-review|Package Review Submission|
+
+\h#package-review-manifest|Package Review Manifest|
+
+The package review manifest files are per version/revision and are normally
+stored on the filesystem along with other package metadata (like ownership
+information). Under the metadata root directory, a review manifest file has
+the following path:
+
+\
+<project>/<package>/<version>/reviews.manifest
+\
+
+For example:
+
+\
+hello/libhello/1.2.3+2/reviews.manifest
+\
+
+Note that review manifests are normally not removed when the corresponding
+package archive is removed (for example, as a result of a replacement with a
+revision) because reviews for subsequent versions may refer to review results
+of previous versions (see below).
+
+The package review file is a manifest list with each manifest containing
+the below values in an unspecified order:
+
+\
+reviewed-by: <string>
+result-<name>: pass|fail|unchanged
+[base-version]: <version>
+[details-url]: <url>
+\
+
+For example:
+
+\
+reviewed-by: John Doe <john@example.org>
+result-build: fail
+details-url: https://github.com/build2-packaging/hello/issues/1
+\
+
+The \c{reviewed-by} value identifies the reviewer. For example, a deployment
+policy may require a real name and email address when submitting a review.
+
+The \c{result-<name>} values specify the review results for various aspects of
+the package. At least one result value must be present and duplicates for the
+same aspect name are not allowed. For example, a deployment may define the
+following aspect names: \c{build} (build system), \c{code} (implementation
+source code), \c{test} (tests), \c{doc} (documentation).
+
+The \c{result-<name>} value must be one of \c{pass} (the review passed),
+\c{fail} (the review failed), and \c{unchanged} (the aspect in question hasn't
+changed compared to the previous version, which is identified with the
+\c{base-version} value; see below).
+
+The \c{base-version} value identifies the previous version on which this
+review is based. The idea here is that when reviewing a new revision, a patch
+version, or even a minor version, it is often easier to review the difference
+between the two versions than to review everything from scratch. In such
+cases, if some aspects haven't changed since the previous version, then their
+results can be specified as \c{unchanged}. The \c{base-version} value must be
+present if at least one \c{result-<name>} value is \c{unchanged}.
+
+The \c{details-url} value specifies a URL that contains the details of the
+review (issues identified, etc). It can only be absent if none of the
+\c{result-<name>} values are \c{fail} (a failed review needs an explanation
+of why it failed).
+
 "
-- 
cgit v1.1