Explain why RacyGitTests may be flaky in some environments

Change-Id: I5bbd04754f5f29299a7b9a58a3717e3f615199d0

1 files changed, 16 insertions, 0 deletions

diff --git a/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/RacyGitTests.java b/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/RacyGitTests.java
index b1d80c5c30..f25e5d10ff 100644
--- a/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/RacyGitTests.java
+++ b/org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/RacyGitTests.java
@@ -30,6 +30,22 @@ import org.junit.Test;
 
 public class RacyGitTests extends RepositoryTestCase {
 
+	/**
+	 * This test is inherently flaky in nature since using clocks in a computer
+	 * to determine file modifications in a filesystem from Java is difficult
+	 * and depends on many factors and we can't test all combinations
+	 *
+	 * If this test fails on your computer, don't worry but let us know if you
+	 * are willing to provide details which may help to further improve handling
+	 * of the racy git problem in JGit.
+	 *
+	 * Despite not being completely reproducible this test is still useful to
+	 * detect regressions when running this test repeatedly on the same
+	 * OS/filesystem/Java version (which we do on the CI used to build JGit).
+	 *
+	 * @see "https://git-scm.com/docs/racy-git"
+	 * @see "https://www.youtube.com/watch?v=m44cAozuLNI"
+	 */
 	@Test
 	public void testRacyGitDetection() throws Exception {
 		// Reset to force creation of index file