Add a README with local development instructions

README.md

@@ -0,0 +1,82 @@
+# Python Library Fuzzers
+
+This repository contains the fuzzer definitions, seed corpora,
+and dictionaries used by [OSS-Fuzz](https://github.com/google/oss-fuzz) to fuzz-test Python standard library modules.
+
+## Getting Started
+
+Read the [getting started](https://google.github.io/oss-fuzz/getting-started/)
+guide for OSS-Fuzz to learn about the [architecture of the fuzzer](https://google.github.io/oss-fuzz/architecture/)
+and the necessary dependencies for local development (Docker, Python).
+
+## Architecture
+
+There are four components of the [OSS-Fuzz architecture](https://google.github.io/oss-fuzz/architecture/)
+hosted in this repository. Other components of
+the OSS-Fuzz architecture are hosted in other repositories.
+
+Components that are hosted in this repository:
+
+* Fuzz target definitions. These are typically `.py` files that are bootstrapped
+  into binaries by `fuzzer.cpp` and `Makefile`.
+* Fuzz seed corpora (`corp-*`): These files contain "starting points" byte
+  sequences that the fuzzer can use to get results quicker than random bytes.
+* Fuzz dictionaries (`*.dict`): These files contain possible byte sequences that
+  the fuzzer can use when mutating input sequences.
+* Coverage header file (`python_coverage.h`): This file is compiled with CPython
+  so that line coverage is tracked over time as the fuzzer executes.
+
+Components that are hosted elsewhere:
+
+* [Project configuration](https://github.com/google/oss-fuzz/tree/master/projects/python3-libraries): 
+  This component controls the OSS-Fuzz project definition, maintainers.
+* [Fuzzer image configuration](https://github.com/google/oss-fuzz/tree/master/projects/python3-libraries):
+  `Dockerfile` and `build.sh` describe how the fuzzer
+  image is built and what fuzz targets are executed by OSS-Fuzz.
+
+When you create a new fuzz target **don't forget to add the target to the fuzzer image**
+so that the fuzz target is executed by OSS-Fuzz.
+
+## Local development
+
+To do develop locally with OSS-Fuzz you need to fork and clone the
+following repositories:
+
+* https://github.com/google/oss-fuzz
+* https://github.com/hugovk/python-library-fuzzers
+* https://github.com/python/cpython
+
+After cloning forks of these repositories, move into the `oss-fuzz`
+repository and run the following to build the base and fuzzer image:
+
+```sh
+python infra/helper.py build_image python3-libraries
+python infra/helper.py build_fuzzers python3-libraries
+
+Once this succeeds you have the proper toolset to locally develop fuzzers.
+You can run fuzz targets using the same helper script:
+
+```sh
+python infra/helper.py run_fuzzer python3-libraries fuzzer-email
+
+This will run the fuzzer indefinitely, so stop the fuzzer whenever
+you've confirmed that it works.
+Now we need to point the `oss-fuzz` repository to our own forks to start
+local development.
+
+Modify the `projects/python3-libraries/Dockerfile` file `git clone` lines
+to point to your own forks (example below using `sethmlarson`). It's recommended
+to use a branch on forks instead of `main`, so the example below also uses
+`--branch fork-branch` which you can change to your own branch depending on
+which repository you are modifying during development.
+
+```diff
+-RUN git clone https://github.com/python/cpython.git cpython
+-RUN git clone --depth 1 https://github.com/hugovk/python-library-fuzzers.git
++RUN git clone --depth 1 --branch fork-branch https://github.com/sethmlarson/cpython.git cpython
++RUN git clone --depth 1 --branch fork-branch https://github.com/sethmlarson/python-library-fuzzers.git
+```
+
+After this you can now re-run the `python infra/helper.py` commands to rebuild the image and fuzzers
+using the fork repositories instead. From here local development proceeds through pushing commits
+to your fork branches, rebuilding the image and fuzzers, and then running the fuzzers.