[PATCH RFC v2 2/4] unit tests: Add a project plan document

From: steadmon@google.com
To: git@vger.kernel.org
Cc: Josh Steadmon <steadmon@google.com>,
	calvinwan@gmail.com, szeder.dev@gmail.com,
	phillip.wood123@gmail.com, chooglen@google.com, avarab@gmail.com,
	gitster@pobox.com, sandals@crustytoothpaste.net
Subject: [PATCH RFC v2 2/4] unit tests: Add a project plan document
Date: Wed, 17 May 2023 16:56:32 -0700	[thread overview]
Message-ID: <20230517-unit-tests-v2-v2-2-21b5b60f4b32@google.com> (raw)
In-Reply-To: <20230517-unit-tests-v2-v2-0-21b5b60f4b32@google.com>

Describe what we hope to accomplish by implementing unit tests, and
explain some open questions and milestones.

Change-Id: I182cdc1c15bdd1cbef6ffcf3d216b386f951e9fc
---
 Documentation/Makefile                 |  1 +
 Documentation/technical/unit-tests.txt | 47 ++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b629176d7d..3f2383a12c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -122,6 +122,7 @@ TECH_DOCS += technical/scalar
 TECH_DOCS += technical/send-pack-pipeline
 TECH_DOCS += technical/shallow
 TECH_DOCS += technical/trivial-merge
+TECH_DOCS += technical/unit-tests
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
 
diff --git a/Documentation/technical/unit-tests.txt b/Documentation/technical/unit-tests.txt
new file mode 100644
index 0000000000..7c575e6ef7
--- /dev/null
+++ b/Documentation/technical/unit-tests.txt
@@ -0,0 +1,47 @@
+= Unit Testing
+
+In our current testing environment, we spend a significant amount of effort
+crafting end-to-end tests for error conditions that could easily be captured by
+unit tests (or we simply forgo some hard-to-setup and rare error conditions).
+Unit tests additionally provide stability to the codebase and can simplify
+debugging through isolation. Writing unit tests in pure C, rather than with our
+current shell/test-tool helper setup, simplifies test setup, simplifies passing
+data around (no shell-isms required), and reduces testing runtime by not
+spawning a separate process for every test invocation.
+
+Unit testing in C requires a separate testing harness that we ideally would
+like to be TAP-style and to come with a non-restrictive license. Fortunately,
+there already exists a https://github.com/rra/c-tap-harness/[C TAP harness
+library] with an MIT license (at least for the files needed for our purposes).
+We might also consider implementing
+https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[our
+own TAP harness] just for Git.
+
+We believe that a large body of unit tests, living alongside the existing test
+suite, will improve code quality for the Git project.
+
+== Open questions
+
+=== TAP harness
+
+We'll need to decide on a TAP harness. The C TAP library is easy to integrate,
+but has a few drawbacks:
+* (copy objections from lore thread)
+* We may need to carry local patches against C TAP. We'll need to decide how to
+  manage these. We could vendor the code in and modify them directly, or use a
+  submodule (but then we'll need to decide on where to host the submodule with
+  our patches on top).
+
+Phillip Wood has also proposed a new implementation of a TAP harness (linked
+above). While it hasn't been thoroughly reviewed yet, it looks to support a few
+nice features that C TAP does not, e.g. lazy test plans and skippable tests.
+
+== Milestones
+
+* Settle on final TAP harness
+* Add useful tests of library-ish code
+* Integrate with CI
+* Integrate with
+  https://lore.kernel.org/git/20230502211454.1673000-1-calvinwan@google.com/[stdlib
+  work]
+* Run along with regular `make test` target

-- 
2.40.1.606.ga4b1b128d6-goog

