docs: Improve instructions for usage of the regenerate flatbuffers script
#!/bin/bash -e
-# The commit where the Rust `flatbuffers` crate version was changed to the version in `Cargo.lock`
-# Update this, rerun this script, and check in the changes in the generated code when the
-# `flatbuffers` crate version is updated.
+# Instructions
+#
+# If you have changed some `*.fbs` files:
+#
+# - Run this script 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 this script.
+#
+# If you are updating the version of the `flatbuffers` crate in `Cargo.lock`:
+#
+# - 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`.
+# - Put that commit SHA in this variable:
FB_COMMIT="86401e078d0746d2381735415f8c2dfe849f3f52"
+# - Run this script 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.
-# Change to the generated_types crate directory, where this script is located
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
pushd $DIR
