From ca80dee5145ff9240aa6b4e342e14332bec9973b Mon Sep 17 00:00:00 2001
From: Matt Morehouse <mattmorehouse@gmail.com>
Date: Mon, 20 Mar 2023 11:36:42 -0500
Subject: [PATCH] doc: add section about improving fuzzing corpora

We want to encourage contributions to the seed corpora that improve
coverage.
---
 doc/FUZZING.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/doc/FUZZING.md b/doc/FUZZING.md
index c2101d1e0..0acb710f0 100644
--- a/doc/FUZZING.md
+++ b/doc/FUZZING.md
@@ -60,7 +60,43 @@ The latter will run all targets two by two `12345` times.
 If you want to contribute new seeds, be sure to merge your corpus with the main one:
 ```
 ./tests/fuzz/run.py my_locally_extended_fuzz_corpus -j2 --generate --runs 12345
-./tests/fuzz/run.py main_fuzz_corpus --merge_dir my_locally_extended_fuzz_corpus
+./tests/fuzz/run.py tests/fuzz/corpora --merge_dir my_locally_extended_fuzz_corpus
+```
+
+
+## Improve seed corpora
+
+If you find coverage increasing inputs while fuzzing, please create a pull
+request to add them into `tests/fuzz/corpora`. Be sure to minimize any additions
+to the corpora first.
+
+### Example
+
+Here's an example workflow to contribute new inputs for the `fuzz-addr` target.
+
+Create a directory for newly found corpus inputs and begin fuzzing:
+
+```shell
+mkdir -p local_corpora/fuzz-addr
+./tests/fuzz/fuzz-addr -jobs=4 local_corpora/fuzz-addr tests/fuzz/corpora/fuzz-addr/
+```
+
+After some time, libFuzzer may find some potential coverage increasing inputs
+and save them in `local_corpora/fuzz-addr`. We can then merge them into the seed
+corpora in `tests/fuzz/corpora`:
+
+```shell
+./tests/fuzz/run.py tests/fuzz/corpora --merge_dir local_corpora
+```
+
+This will copy over any inputs that improve the coverage of the existing corpus.
+If any new inputs were added, create a pull request to improve the upstream seed
+corpus:
+
+```shell
+git add tests/fuzz/corpora/fuzz-addr/*
+git commit
+...
 ```