Add a section on keeping things up to date in the git section

3 files changed, 47 insertions, 7 deletions

diff --git a/src/doc/rustc-dev-guide/src/about-this-guide.md b/src/doc/rustc-dev-guide/src/about-this-guide.md
index d12f5a7a34a..0ba753a6259 100644
--- a/src/doc/rustc-dev-guide/src/about-this-guide.md
+++ b/src/doc/rustc-dev-guide/src/about-this-guide.md
@@ -10,8 +10,8 @@ There are six parts to this guide:
    useful no matter how you are contributing, about building, debugging,
    profiling, etc.
 2. [Contributing to `rustc`][p1-5]: Contains information that should be useful
-   no matter how you are contributing, about procedures for contribution,
-   stabilizing features, etc.
+   no matter how you are contributing, about procedures for contribution, using git
+   and Github, stabilizing features, etc.
 2. [High-Level Compiler Architecture][p2]: Discusses the high-level
    architecture of the compiler and stages of the compile process.
 3. [Source Code Representation][p3]: Describes the process of taking raw source code from the user and
diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md
index cf049015d96..d8f7a79a1df 100644
--- a/src/doc/rustc-dev-guide/src/contributing.md
+++ b/src/doc/rustc-dev-guide/src/contributing.md
@@ -64,7 +64,8 @@ Pull requests (or PRs for short) are the primary mechanism we use to change Rust
 GitHub itself has some [great documentation][about-pull-requests] on using the
 Pull Request feature. We use the "fork and pull" model [described here][development-models],
 where contributors push changes to their personal fork and create pull requests to
-bring those changes into the source repository.
+bring those changes into the source repository. We have more info about how to use git
+when contributing to Rust under [the git section](./git.md).
 
 [about-pull-requests]: https://help.github.com/articles/about-pull-requests/
 [development-models]: https://help.github.com/articles/about-collaborative-development-models/
diff --git a/src/doc/rustc-dev-guide/src/git.md b/src/doc/rustc-dev-guide/src/git.md
index e10f1d7050b..fb64b3bcab4 100644
--- a/src/doc/rustc-dev-guide/src/git.md
+++ b/src/doc/rustc-dev-guide/src/git.md
@@ -46,6 +46,10 @@ git remote add upstream git@github.com:rust-lang/rust.git
 
 if you're using SSH.
 
+**NOTE:** This page is dedicated to workflows for `rust-lang/rust`, but will likely be
+useful when contributing to other repositories in the Rust project.
+
+
 ## Standard Process
 
 Below is the normal procedure that you're likely to use for most minor changes
@@ -53,7 +57,8 @@ and PRs:
 
  1. Ensure that you're making your changes on top of master:
  `git checkout master`.
- 2. Get the latest changes from the Rust repo: `git pull upstream master`.
+ 2. Get the latest changes from the Rust repo: `git pull upstream master --ff-only`.
+ (see [No-Merge Policy](#keeping-things-up-to-date) for more info about this).
  3. Make a new branch for your change: `git checkout -b issue-12345-fix`.
  4. Make some changes to the repo and test them.
  5. Stage your changes via `git add src/changed/file.rs src/another/change.rs`
@@ -62,8 +67,13 @@ and PRs:
  unintentionally commit changes that should not be committed, such as submodule
  updates. You can use `git status` to check if there are any files you forgot
  to stage.
- 6. Push your changes to your fork: `git push --set-upstream origin issue-12345-fix`.
- 7. [Open a PR][ghpullrequest] from your fork to rust-lang/rust's master branch.
+ 6. Push your changes to your fork: `git push --set-upstream origin issue-12345-fix`
+ (After adding commits, you can use `git push` and after rebasing or
+pulling-and-rebasing, you can use `git push --force-with-lease`).
+ 7. If you end up needing to rebase and are hitting conflicts, see [Rebasing](#rebasing).
+ 8. If you want to track upstream while working on long-running feature/issue, see
+ [Keeping things up to date](#keeping-things-up-to-date).
+ 9. [Open a PR][ghpullrequest] from your fork to `rust-lang/rust`'s master branch.
 
 [ghpullrequest]: https://guides.github.com/activities/forking/#making-a-pull-request
 
@@ -160,7 +170,7 @@ it's not anything you did wrong. There is a workaround at [#77620].
 
 [#77620]: https://github.com/rust-lang/rust/issues/77620#issuecomment-705228229
 
-## Conflicts
+## Rebasing and Conflicts
 
 When you edit your code locally, you are making changes to the version of
 rust-lang/rust that existed when you created your feature branch. As such, when
@@ -236,6 +246,34 @@ The advice this gives is incorrect! Because of Rust's
 will not be allowed in the final PR, in addition to defeating the point of the
 rebase! Use `git push --force-with-lease` instead.
 
+### Keeping things up to date
+
+The above section on [Rebasing](#rebasing) is a specific
+guide on rebasing work and dealing with merge conflicts.
+Here is some general advice about how to keep your local repo
+up-to-date with upstream changes:
+
+Using `git pull upstream master` while on your local master branch regularly
+will keep it up-to-date. You will also want to rebase your feature branches
+up-to-date as well. After pulling, you can checkout the feature branches
+and rebase them:
+
+```
+git checkout master
+git pull upstream master --ff-only # to make certain there are no merge commits
+git checkout feature_branch
+git rebase master
+git push --force-with-lease (set origin to be the same as local)
+```
+
+To avoid merges as per the [No-Merge Policy][#no-merge-policy], you may want to use
+`git config pull.ff only` (this will apply the config to the local repo).
+to avoid merge conflicts while pulling, without needing
+`--ff-only` or `--rebase` while `git pull`ing
+
+You can also `git push --force-with-lease` from master to keep your origin's master in sync with
+upstream.
+
 ## Advanced Rebasing
 
 If your branch contains multiple consecutive rewrites of the same code, or if
@@ -330,6 +368,7 @@ that merge commits in PRs are not accepted. As a result, if you are running
 course, this is not always true; if your merge will just be a fast-forward,
 like the merges that `git pull` usually performs, then no merge commit is
 created and you have nothing to worry about. Running `git config merge.ff only`
+(this will apply the config to the local repo).
 once will ensure that all the merges you perform are of this type, so that you
 cannot make a mistake.