Added misc notes.

1 files changed, 91 insertions, 0 deletions

diff --git a/doc/notes.txt b/doc/notes.txt
new file mode 100644
index 0000000..466e055
--- /dev/null
+++ b/doc/notes.txt
@@ -0,0 +1,91 @@
+A benchmark is the combination of a test case, test function, and a data tag.
+
+
+------------
+Definition: BMCONTEXT = <benchmark> <metric> <platform> <host>
+
+Note: In general, comparisons are meaningful only within the same
+BMCONTEXT. This assumption will be enforced in the user interface described
+below.
+
+
+------------
+The xml file (produced by QTestLib) contains the benchmark (text case, test
+function, and data tag), metric, and result (value and iterations).
+
+When used as a standalone term, a branch refers to the combination of a Git
+repository and a Git branch.
+
+
+------------
+Definition: SNAPSHOT = -timestamp <secs since epoch> | -sha1 <sha1>
+
+A -timestamp value t has the following semantics:
+
+   t = -1: the latest result ('last' may be used as an alias)
+   t >= 0: the earliest result that is not earlier than t ('first' may be used as an alias for 0)
+
+Note: The -sha1 option requires exact matching and is thus less powerful than -timestamp.
+
+
+----------------------
+
+Use case 1: Compare results for a given branch since a given snapshot:
+
+    ./bmc compare -history BMCONTEXT -branch <branch> SNAPSHOT
+
+Use case 2: Compare the results of two branches:
+
+    ./bmc compare -branches BMCONTEXT <branch1> SNAPSHOT1 <branch2> SNAPSHOT2
+
+Use case 3: Compare a result of a given branch directly to an unregistered
+     result (i.e. one not yet in the DB):
+
+    ./bmc compare -direct BMCONTEXT <branch> SNAPSHOT (<value> <iterations>) | <xml file>
+
+    Note: If an xml file is specified, it is assumed to contain a
+    value/iterations pair that matches the benchmark and metric in the
+    BMCONTEXT.
+
+----------------------------------
+
+Use case 4: Add new results:
+
+    ./bmc add -results <xml file> -platform <platform> -host <host> \
+        -gitrepo <product git repo> [-gitdir <product git dir>] [-sha1 <product sha1>]
+
+    Notes:
+       - <product git dir> must refer to a directory accessible from the local
+         file system.
+       - The new results are assumed to have been generated using a product
+         built from a working tree having <product sha1> as the head commit.
+       - By default, <product git dir> is the current directory.
+       - By default, <product sha1> is the current head commit of the working tree
+         in <product git dir>.
+       - The git branch is derived from <product git dir> (using the 'git branch' command).
+       - The timestamp (to accompany the sha1 in the database) is derived from
+         the combination of the git branch and <product sha1> in
+         <product git dir> (using the 'git show ... --pretty=raw' command).
+       - In general, the git repository name cannot be derived from <product
+         git dir> (e.g. in the case of a local, standalone repository). That's
+         why it must be passed explicitly.
+
+----------------------------------
+
+Use case 5: List available benchmarks (subject to optional restrictions):
+
+    ./bmc list -benchmarks [-metric <metric>] [-platform <platform>] [-host <host>] \
+        [-branch <branch>]
+
+Ditto for other entities:
+
+    ./bmc list -metrics ...
+    ./bmc list -platforms ...
+    ./bmc list -hosts ...
+    ./bmc list -branches ...
+
+----------------------------------
+
+Use case 6: List available snapshots for a given branch:
+
+    ./bmc list snapshots BMCONTEXT <branch>