update boringssl instructions

third_party/README.md

@@ -37,23 +37,51 @@ Usually the process is
 
 Updating some dependencies requires extra care.
 
-### Updating third_party/boringssl-with bazel
-
-- Update the `third_party/boringssl-with-bazel` submodule to the latest `master-with-bazel` branch
-
-- Update boringssl dependency in `grpc_deps.bzl` to the same commit
+### Updating third_party/boringssl-with-bazel
+
+- Update the `third_party/boringssl-with-bazel` submodule to the latest [`master-with-bazel`](https://github.com/google/boringssl/tree/master-with-bazel) branch
+```
+git submodule update --init      # just to start in a clean state
+cd third_party/boringssl-with-bazel
+git fetch origin   # fetch what's new in the boringssl repository
+git checkout origin/master-with-bazel  # checkout the current state of master-with-bazel branch in the boringssl repo
+# Note the latest commit SHA on master-with-bazel-branch 
+cd ../..   # go back to grpc repo root
+git status   #  will show that there are new commits in third_party/boringssl-with-bazel
+git add  third_party/boringssl-with-bazel     # we actually want to update the changes to the submodule
+git commit -m "update submodule boringssl-with-bazel with origin/master-with-bazel"   # commit
+```
+
+- Update boringssl dependency in `bazel/grpc_deps.bzl` to the same commit SHA as master-with-bazel branch
+    - Update `http_archive(name = "boringssl",` section by updating the sha in `strip_prefix` and `urls` fields.
+    - Also, set `sha256` field to “” as the existing value is not valid. This will be added later once we know what that value is.
 
 - Update `tools/run_tests/sanity/check_submodules.sh` with the same commit
 
+- Commit these changes `git commit -m "update boringssl dependency to master-with-bazel commit SHA"`
+
 - Run `tools/buildgen/generate_projects.sh` to regenerate the generated files
+    - Because `sha256` in `bazel/grpc_deps.bzl` was left empty, you will get a DEBUG msg like this one:
+```
+Rule 'boringssl' indicated that a canonical reproducible form can be obtained by modifying arguments sha256 = "SHA value"
+```
+    - Commit the regenrated files `git commit -m "regenerate files"`
+    - Update `bazel/grpc_deps.bzl` with the SHA value shown in the above debug msg. Commit again `git commit -m "Updated sha256"`
 
-- Run `tools/distrib/generate_grpc_shadow_boringssl_symbol_list.sh`
+- Run `tools/distrib/generate_boringssl_prefix_header.sh`
+    - Commit again `commit -m "generate boringsll prefix headers"`
 
 - Increment the boringssl podspec version number in 
   `templates/src/objective-c/BoringSSL-GRPC.podspec.template` and `templates/gRPC-Core.podspec.template`.
   [example](https://github.com/grpc/grpc/pull/21527/commits/9d4411842f02f167209887f1f3d2b9ab5d14931a)
+    - Commit again `commit -m "Increment podspec version"`
 
 - Run `tools/buildgen/generate_projects.sh` (yes, again)
+    - Commit again `commit -m "Second regeneration"`
+
+- Create a PR with all the above commits.
+
+- Run `bazel/update_mirror.sh` to update GCS mirror.
 
 ### Updating third_party/protobuf