[RFC/PoC 1/5] doc: provide DocBundles design document

From

Philip Oakley <philipoakley@iee.email>

Date

Nov 2, 2022, 22:48 UTC

Message-ID

<20221102224843.2104-2-philipoakley@iee.email>

In-Reply-To

<20221102224843.2104-1-philipoakley@iee.email>

Signed-off-by: Philip Oakley <philipoakley@iee.email>
---
 Documentation/technical/docbundle.txt | 97 +++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 Documentation/technical/docbundle.txt

diff --git a/Documentation/technical/docbundle.txt b/Documentation/technical/docbundle.txt
new file mode 100644
index 0000000000..8c17a7847f
--- /dev/null
+++ b/Documentation/technical/docbundle.txt
@@ -0,0 +1,97 @@
+docbundle Design Document
+=========================
+
+The Git man pages contain many example setups to demonstrate aspects
+of the related Git commands, such as history simplification in the `log`
+and `show commands. However, while illustrative, these are not
+accessible, as example repositories, to regular, potentially confused,
+users who may need to understand the set up of the examples.
+
+The docbundle concept is that for each of these examples there is a
+matching `bundle` file, provided with the Documentation, which can be
+simply cloned to provide an example repository containing the example.
+
+There are also many example repositories in the Git `/t` test system
+that could be exposed to users which already demonstrate some important
+testable aspect of Git within a carefully constructed repository.
+
+
+This proposal is to provide DocBundles to users via the Git project.
+
+
+Firstly, it should be reasonably self-evident that the man page examples
+should, in themselves, be tested for accuracy, especially if provided
+to users.
+
+Secondly, the existing test system is the proper place to setup and
+test any such docbundle repositories.
+
+Third, that the bundle is an obvious pre-existing mechanism for
+transporting repositories (see also the Bundle-URI proposals).
+
+Fourthly, the preparation and distribution of the docbundle should
+require minimal maintainer effort, preferably being integrated into
+the existing automation for Documentation preparation and distribution.
+
+Fifthly, the docbudles themselves should not to be part of the git.git
+repo. They are prepared via the test suite and should be stored (locally)
+in a designated Git_DocBundle_Dir, and be .gitignored. The DocBundles
+are transferred to the maintainer's Doc repo via the automation.
+
+Sixthly, the docbundles to be named based on their `tnnnn` test number
+and a (short) descriptive name.
+
+Seven, (dev) start with an existing test, rather than add a test (most
+doc/man examples aren't tested!). Add tests for missing examples later.
+
+Eight, (option) add a `git docbundle` command to assist in locating and
+listing the docbundle examples. It also provides place to explain their
+purpose as "Tutorial Examples" (Note, many existing examples are to
+illustrate complex/difficult scenarios where the wording was insufficient;
+the docbudles are minimal examples).
+
+
+Status
+======
+
+This is an RFC/PoC (Request for Comment / Proof of Concept).
+
+The attached commits establish:
+
+Set out this design in the Documentation/technical directory.
+
+A default location for the docbundles and an env variable to allow
+flexibility by extending test-lib.
+
+The docbundles are ignored, as is the default directory.
+
+Two docbundles are generated from a 'random' test that I happened to
+have open in my editor (t6102 rev-list-simplify).
+
+The docbundle creation is protected by `test_expect_success` wrappers.
+
+
+
+ToDo
+====
+
+DocBundles - Is this the best name, or just a convenient way of
+indicating the delivery mechanism?
+
+Add Prerequisite to control if docbundles are generated (don't waste
+maintainers PC time when not needed).
+
+CI integration (i.e. whether to test the bundling aspect - should be
+reliable).
+
+How to update the man pages, perhaps by inclusion of the test comment
+(exported?), and distinguish between man page descriptions (being
+packaged by the test suite) and tests which offer users insight into
+Git operations, usually with 'interesting' commit-graph set-ups.
+
+Claim t999x as the man doc bundle test sequence ('999' is the UK
+emergency ("Help!") number; 911, 101 and 102 are taken test areas.
+
+Other stuff implicit in the eight point list
+
+

-- 
2.38.1.281.g83ef3ded8d