Update the "Updating LLVM" documentation (#451)

Make sure existing sections are up-to-date and then also add some words
about the recent convention we developed for updating LLVM versions with
respect to branch naming as well.

Author: alexcrichton

src/codegen/updating-llvm.md

@@ -17,23 +17,26 @@ policy!), but for now these are rough guidelines!
 
 ## Why update LLVM?
 
-There are two primary reasons nowadays that we want to update LLVM in one way or
+There are a few reasons nowadays that we want to update LLVM in one way or
 another:
 
-* First, a bug could have been fixed! Often we find bugs in the compiler and fix
+* A bug could have been fixed! Often we find bugs in the compiler and fix
   them upstream in LLVM. We'll want to pull fixes back to the compiler itself as
   they're merged upstream.
 
-* Second, a new feature may be available in LLVM that we want to use in rustc,
+* A new feature may be available in LLVM that we want to use in rustc,
   but we don't want to wait for a full LLVM release to test it out.
 
+* LLVM itself may have a new release and we'd like to update to this LLVM
+  release.
+
 Each of these reasons has a different strategy for updating LLVM, and we'll go
-over both in detail here.
+over them in detail here.
 
 ## Bugfix Updates
 
-For updates of LLVM that typically just update a bug, we cherry-pick the bugfix
-to the branch we're already using. The steps for this are:
+For updates of LLVM that are to fix a small bug, we cherry-pick the bugfix to
+the branch we're already using. The steps for this are:
 
 1. Make sure the bugfix is in upstream LLVM.
 2. Identify the branch that rustc is currently using. The `src/llvm-project`
@@ -43,10 +46,13 @@ to the branch we're already using. The steps for this are:
 4. Check out the appropriate branch (typically named `rustc/a.b-yyyy-mm-dd`)
 5. Cherry-pick the upstream commit onto the branch
 6. Push this branch to your fork
-7. Send a Pull Request to rust-lang/llvm-project to the same branch as before
+7. Send a Pull Request to rust-lang/llvm-project to the same branch as before.
+   Be sure to reference the Rust and/or LLVM issue that you're fixing in the PR
+   description.
 8. Wait for the PR to be merged
 9. Send a PR to rust-lang/rust updating the `src/llvm-project` submodule with
-   your bugfix
+   your bugfix. This can be done locally with `git submodule update --remote
+   src/llvm-project` typically.
 10. Wait for PR to be merged
 
 The tl;dr; is that we can cherry-pick bugfixes at any time and pull them back
@@ -70,28 +76,21 @@ through each in detail.
 1. Create a new branch in the rust-lang/llvm-project repository. This branch
    should be named `rustc/a.b-yyyy-mm-dd` where `a.b` is the current version
    number of LLVM in-tree at the time of the branch and the remaining part is
-   today's date.
+   today's date. Move this branch to the commit in LLVM that you'd like, which
+   for this is probably the current LLVM HEAD.
 
 2. Apply Rust-specific patches to the llvm-project repository. All features and
    bugfixes are upstream, but there's often some weird build-related patches
    that don't make sense to upstream which we have on our repositories. These
    patches are around the latest patches in the rust-lang/llvm-project branch
    that rustc is currently using.
 
-3. Update the `compiler-rt` submodule in the
-   `rust-lang-nursery/compiler-builtins` repository. Push this update to the
-   same branch name of the `llvm-project` submodule to the
-   of the `rust-lang/compiler-rt` repository. Then push this update to a branch
-   of `compiler-builtins` with the same-named branch. Note that this step is
-   frequently optional since we may not need to update `compiler-rt`.
-
-4. Prepare a commit to rust-lang/rust
-
-  * Update `src/llvm-project`
-  * Update `compiler-builtins` crate in `Cargo.lock` (if necessary)
-
-5. Build your commit. Make sure you've committed the previous changes to ensure
-   submodule updates aren't reverted. Some commands you should execute are:
+3. Build the new LLVM in the `rust` repository. To do this you'll want to update
+   the `src/llvm-project` repository to your branch and the revision you've
+   created. It's also typically a good idea to update `.gitmodules` with the new
+   branch name of the LLVM submodule. Make sure you've committed changes to
+   `src/llvm-project` to ensure submodule updates aren't reverted. Some commands
+   you should execute are:
 
    * `./x.py build src/llvm` - test that LLVM still builds
    * `./x.py build src/tools/lld` - same for LLD
@@ -101,7 +100,7 @@ through each in detail.
    LLVM bindings. Note that you should use `#ifdef` and such to ensure that the
    bindings still compile on older LLVM versions.
 
-6. Test for regressions across other platforms. LLVM often has at least one bug
+4. Test for regressions across other platforms. LLVM often has at least one bug
    for non-tier-1 architectures, so it's good to do some more testing before
    sending this to bors! If you're low on resources you can send the PR as-is
    now to bors, though, and it'll get tested anyway.
@@ -120,11 +119,20 @@ through each in detail.
    * `./src/ci/docker/run.sh dist-various-2`
    * `./src/ci/docker/run.sh armhf-gnu`
 
-7. Send a PR! Hopefully it's smooth sailing from here :).
+5. Prepare a PR to `rust-lang/rust`. Work with maintainers of
+   `rust-lang/llvm-project` to get your commit in a branch of that repository,
+   and then you can send a PR to `rust-lang/rust`. You'll change at least
+   `src/llvm-project` and will likely also change `src/rustllvm/*` as well.
 
 For prior art, previous LLVM updates look like
 [#55835](https://github.com/rust-lang/rust/pull/55835)
 [#47828](https://github.com/rust-lang/rust/pull/47828)
+[#62474](https://github.com/rust-lang/rust/pull/62474)
+[#62592](https://github.com/rust-lang/rust/pull/62592). Note that sometimes it's
+easiest to land `src/rustllvm/*` compatibility as a PR before actually updating
+`src/llvm-project`. This way while you're working through LLVM issues others
+interested in trying out the new LLVM can benefit from work you've done to
+update the C++ bindings.
 
 ### Caveats and gotchas
 
@@ -134,8 +142,36 @@ keep in mind while going through them:
 * LLVM bugs are hard to find, don't hesitate to ask for help! Bisection is
   definitely your friend here (yes LLVM takes forever to build, yet bisection is
   still your friend)
-* Updating LLDB has some Rust-specific patches currently that aren't upstream.
-  If you have difficulty @tromey can likely help out.
 * If you've got general questions, @alexcrichton can help you out.
 * Creating branches is a privileged operation on GitHub, so you'll need someone
   with write access to create the branches for you most likely.
+
+## New LLVM Release Updates
+
+Updating to a new release of LLVM is very similar to the "feature updates"
+section above. The release process for LLVM is often months-long though and we
+like to ensure compatibility ASAP. The main tweaks to the "feature updates"
+section above is generally around branch naming. The sequence of events
+typically looks like:
+
+1. LLVM announces that its latest release version has branched. This will show
+   up as a branch in https://github.com/llvm/llvm-project typically named
+   `release/$N.x` where `$N` is the version of LLVM that's being released.
+
+2. We then follow the "feature updates" section above to create a new branch of
+   LLVM in our rust-lang/llvm-project repository. This follows the same naming
+   convention of branches as usual, except that `a.b` is the new version. This
+   update is eventually landed in the rust-lang/rust repository.
+
+3. Over the next few months, LLVM will continually push commits to its
+   `release/a.b` branch. Often those are bug fixes we'd like to have as well.
+   The merge process for that is to use `git merge` itself to merge LLVM's
+   `release/a.b` branch with the branch created in step 2. This is typically
+   done multiple times when necessary while LLVM's release branch is baking.
+
+4. LLVM then announces the release of version `a.b`.
+
+5. After LLVM's official release, we follow the "feature update" section again
+   to create a new branch in the rust-lang/llvm-project repository, this time
+   with a new date. The commit history should look much cleaner as just a few
+   Rust-specific commits stacked on top of stock LLVM's release branch.