docs: Bring markdown about flatbuffers in line with script's docs, mention LOCAL=1
# Regenerating Flatbuffers code
-When updating the version of the [flatbuffers](https://crates.io/crates/flatbuffers) Rust crate used as a dependency in the IOx workspace, the generated Rust code in `generated_types/src/wal_generated.rs` also needs to be updated in sync.
+If you have changed some `*.fbs` files:
-To update the generated code, edit `generated_types/regenerate-flatbuffers.sh` and set the `FB_COMMIT` variable at the top of the file to the commit SHA of the same commit in the [flatbuffers repository](https://github.com/google/flatbuffers) where the `flatbuffers` Rust crate version was updated. This ensures we'll be [using the same version of `flatc` that the crate was tested with](https://github.com/google/flatbuffers/issues/6199#issuecomment-714562121).
+- Run `./generated_types/regenerate-flatbuffers.sh` to regenerate the corresponding Rust code.
+- Run `cargo test` to make sure everything works as you would expect.
+- Check in the changes to the generated code along with your changes to the `*.fbs` files.
+- You should not need to edit the `generated_types/regenerate-flatbuffers.sh` script.
-Then run the `generated_types/regenerate-flatbuffers.sh` script and check in any changes. Check the whole project builds.
+If you are updating the version of the `flatbuffers` crate in `Cargo.lock`, either because a new
+patch release has come out that is compatible with the version range in `Cargo.toml` and you have
+run `cargo update`, or because you've updated the version constraint in `Cargo.toml` to change to a
+new major or minor version:
-`generated_types/regenerate-flatbuffers.sh` will build `flatc` from source if it cannot be found.
-In order to do that your system will require `bazel`; you can likely install this with your favourite package manager.
+- The `flatbuffers` crate gets developed in sync with the `flatc` compiler in the same repo,
+ so when updating the `flatbuffers` crate we also need to update the `flatc` compiler we're
+ using.
+- Go to https://github.com/google/flatbuffers/blame/master/rust/flatbuffers/Cargo.toml and find
+ the commit SHA where the `version` metadata was updated to the version of the `flatbuffers`
+ crate we now want to have in our `Cargo.lock`.
+- In the `generated_types/regenerate-flatbuffers.sh` script, put that commit SHA in the `FB_COMMIT`
+ variable.
+- Run `./generated_types/regenerate-flatbuffers.sh` to regenerate the corresponding Rust code.
+- Run `cargo test` to make sure everything works as you would expect.
+- Check in the changes to the generated code along with your changes to the `Cargo.lock` file,
+ `Cargo.toml` file if relevant, and the `generated_types/regenerate-flatbuffers.sh` script.
+
+By default, the `generated_types/regenerate-flatbuffers.sh` script will run a Docker container that
+uses the same image we use in CI that will have all the necessary dependencies. If you don't want
+to use Docker, run this script with `LOCAL=1`, which will require you to have `bazel` available.
+You can likely install `bazel` with your favourite package manager.
