diff --git a/docs/contributing.md b/docs/contributing.md
index 697cacf59..edac3f3d6 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -130,3 +130,25 @@ These are listed roughly in order of decreasing importance.
 6. To run tests more quickly, use `cargo nextest run --workspace`. To
    use `nextest` with `insta`,
    use `cargo insta test --workspace --test-runner nextest`.
+ 
+ ## Modifying protobuffers (this is not common)
+ 
+ Occasionally, you may need to change the `.proto` files that define jj's data
+ storage format. In this case, you will need to add a few steps to the above
+ workflow.
+ 
+ - Install the `protoc` compiler. This usually means either `apt-get install
+   protobuf-compiler` or downloading [an official release]. The 
+   [`prost` library docs] have additional advice.
+ - Run `cargo run -p gen-protos` regularly (or after every edit to a `.proto`
+   file). This is the same as running `cargo run` from `lib/gen-protos`. The
+   `gen-protos` binary will use the `prost-build` library to compile the
+   `.proto` files into `.rs` files.
+ - If you are adding a new `.proto` file, you will need to edit the list of
+   these files in `lib/gen-protos/src/main.rs`.
+
+[an official release]: https://github.com/protocolbuffers/protobuf/releases
+[`prost` library docs]: https://docs.rs/prost-build/latest/prost_build/#sourcing-protoc
+
+ The `.rs` files generated from `.proto` files are included in the repository,
+ and there is a Github CI check that will complain if they do not match.