From 7bfcf8763b8c963fbaf36fc58455bb3eca0c787d Mon Sep 17 00:00:00 2001 From: Gus Wynn Date: Wed, 20 Jan 2021 08:17:29 -0800 Subject: [PATCH] Add a section on keeping things up to date in the git section --- src/about-this-guide.md | 4 ++-- src/contributing.md | 3 ++- src/git.md | 47 +++++++++++++++++++++++++++++++++++++---- 3 files changed, 47 insertions(+), 7 deletions(-) diff --git a/src/about-this-guide.md b/src/about-this-guide.md index d12f5a7a..0ba753a6 100644 --- a/src/about-this-guide.md +++ b/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/contributing.md b/src/contributing.md index cf049015..d8f7a79a 100644 --- a/src/contributing.md +++ b/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/git.md b/src/git.md index e10f1d70..fb64b3bc 100644 --- a/src/git.md +++ b/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.