Document the test fixture bundle in CONTRIBUTING.md

Explains what tests/fixtures/foobar.bundle is, how to regenerate it to
add a new fixture scenario, and why tests/fixtures/verify-bundle.sh
exists and needs updating alongside any intentional change to the
bundle's refs or size.

Author: lyrixx

.github/CONTRIBUTING.md

@@ -39,6 +39,34 @@ $ vendor/bin/phpunit
 
 * A script `test-git-versions.sh` is available in repository to test gitlib against many git versions.
 * The tests will be automatically run by [GitHub Actions](https://github.com/features/actions) against pull requests.
+* Tests run fully offline: no network access is required.
+
+## Test fixtures
+
+Most tests run against a fixture repository cloned from `tests/fixtures/foobar.bundle`,
+a git bundle of [gitonomy/foobar](https://github.com/gitonomy/foobar). Using a local
+bundle instead of cloning the repository over the network keeps the tests fast, offline,
+and independent of that repository's history.
+
+If you need a new fixture scenario (a specific merge, encoding, or signed-commit shape,
+for example), regenerate the bundle from a clone of `gitonomy/foobar` with your changes
+added, using the same set of refs already in the bundle:
+
+```bash
+$ git clone https://github.com/gitonomy/foobar.git /tmp/foobar && cd /tmp/foobar
+# ... add your commits, branches or tags ...
+$ git bundle create foobar.bundle \
+    HEAD refs/heads/master refs/heads/new-feature refs/heads/diff-features \
+    refs/heads/pagination refs/heads/path-resolving refs/tags/0.1 refs/tags/annotated
+$ cp foobar.bundle /path/to/gitlib/tests/fixtures/foobar.bundle
+```
+
+Then update the commit SHA constants in `AbstractTestCase` to match, and run
+`tests/fixtures/verify-bundle.sh`. It checks the bundle's integrity, its ref list against
+an allow-list, and its size, since GitHub renders any change to this binary file as an
+opaque diff. If your change intentionally adds a ref or grows the file, update
+`ALLOWED_REFS` or `MAX_SIZE_KB` in that script as part of the same pull request, so the
+reason for the change is explicit and reviewable rather than a silent binary diff.
 
 ## Standard code