Document outcome of black/white box discussion

1 files changed, 17 insertions, 1 deletions

diff --git a/STYLE.md b/STYLE.md
index 3a6ae2bad..bc0bfc005 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -107,4 +107,20 @@ instead of:
 func (server) GetBlob(_ *pb.GetBlobRequest, _ pb.BlobService_GetBlobServer) error {
     return helper.Unimplemented
 }
-```
\ No newline at end of file
+```
+
+## Black box and white box testing
+
+The dominant style of testing in Gitaly is "white box" testing, meaning
+test functions for package `foo` declare their own package also to be
+`package foo`. This gives the test code access to package internals. Go
+also provides a mechanism sometimes called "black box" testing where the
+test functions are not part of the package under test: you write
+`package foo_test` instead. Depending on your point of view, the lack of
+access to package internals when using black-box is either a bug or a
+feature.
+
+As a team we are currently divided on which style to prefer so we are
+going to allow both. In areas of the code where there is a clear
+pattern, please stick with the pattern. For example, almost all our
+service tests are white box.