diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index efb21726e..c924216b8 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -68,7 +68,7 @@ This instructs `git` to perform a "shallow clone", cloning the repository but tr the last `N` commits. Passing `--depth 1` tells `git` to clone the repository but truncate the history to the latest -commit that is on the `master` branch, which is usually fine for browsing the source code or +commit that is on the `main` branch, which is usually fine for browsing the source code or building the compiler. ```bash @@ -172,7 +172,7 @@ You can install it with `cargo install --path src/tools/x`. To clarify that this is another global installed binary util, which is similar to the one declared in section [What is `x.py`](#what-is-xpy), but -it works as an independent process to execute the `x.py` rather than calling the +it works as an independent process to execute the `x.py` rather than calling the shell to run the platform related scripts. ## Create a `bootstrap.toml` diff --git a/src/building/suggested.md b/src/building/suggested.md index 6d7d340e6..1c75de3e9 100644 --- a/src/building/suggested.md +++ b/src/building/suggested.md @@ -296,7 +296,7 @@ lets you use `cargo fmt`. [the section on vscode]: suggested.md#configuring-rust-analyzer-for-rustc [the section on rustup]: how-to-build-and-run.md?highlight=rustup#creating-a-rustup-toolchain -## Faster Builds with CI-rustc +## Faster Builds with CI-rustc If you are not working on the compiler, you often don't need to build the compiler tree. For example, you can skip building the compiler and only build the `library` tree or the @@ -389,7 +389,7 @@ times, and having to update each clone individually. Fortunately, Git has a better solution called [worktrees]. This lets you create multiple "working trees", which all share the same Git database. Moreover, because all of the worktrees share the same object database, if you update a -branch (e.g. master) in any of them, you can use the new commits from any of the +branch (e.g. `main`) in any of them, you can use the new commits from any of the worktrees. One caveat, though, is that submodules do not get shared. They will still be cloned multiple times. @@ -403,10 +403,10 @@ command: git worktree add ../rust2 ``` -Creating a new worktree for a new branch based on `master` looks like: +Creating a new worktree for a new branch based on `main` looks like: ```bash -git worktree add -b my-feature ../rust2 master +git worktree add -b my-feature ../rust2 main ``` You can then use that rust2 folder as a separate workspace for modifying and diff --git a/src/contributing.md b/src/contributing.md index e30819ebc..1b4f04dbb 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -55,7 +55,7 @@ Instead, we have 3 release channels: stable, beta, and nightly. - **Stable**: this is the latest stable release for general usage. - **Beta**: this is the next release (will be stable within 6 weeks). -- **Nightly**: follows the `master` branch of the repo. +- **Nightly**: follows the `main` branch of the repo. This is the only channel where unstable features are intended to be used, which happens via opt-in feature gates. @@ -97,7 +97,7 @@ before approving). This is yet another bot that will compile a collection of benchmarks on a compiler with your changes. The numbers are reported -[here][perf], and you can see a comparison of your changes against the latest master. +[here][perf], and you can see a comparison of your changes against the latest `main`. > For an introduction to the performance of Rust code in general > which would also be useful in rustc development, see [The Rust Performance Book]. @@ -153,7 +153,7 @@ We have [a chapter](git.md) on how to use Git when contributing to Rust. ### Keeping your branch up-to-date -The CI in rust-lang/rust applies your patches directly against the current master, +The CI in rust-lang/rust applies your patches directly against the current `main`, not against the commit your branch is based on. This can lead to unexpected failures if your branch is outdated, even when there are no explicit merge conflicts. @@ -164,7 +164,7 @@ During review, make incremental commits to address feedback. Prefer to squash or rebase only at the end, or when a reviewer requests it. When updating, use `git push --force-with-lease` and leave a brief comment explaining what changed. -Some repos prefer merging from `upstream/master` instead of rebasing; +Some repos prefer merging from `upstream/main` instead of rebasing; follow the project's conventions. See [keeping things up to date](git.md#keeping-things-up-to-date) for detailed instructions. @@ -264,7 +264,7 @@ It will look something like this: This tells [@bors], our lovable integration bot, that your pull request has been approved. The PR then enters the [merge queue], where [@bors] will run *all* the tests on *every* platform we support. -If it all works out, [@bors] will merge your code into `master` and close the pull request. +If it all works out, [@bors] will merge your code into `main` and close the pull request. Depending on the scale of the change, you may see a slightly different form of `r+`: @@ -288,7 +288,7 @@ You are now ready to file a pull request (PR)? Great! Here are a few points you should be aware of. -All pull requests should be filed against the `master` branch, +All pull requests should be filed against the `main` branch, unless you know for sure that you should target a different branch. Run some style checks before you submit the PR: @@ -303,7 +303,7 @@ Rust follows a _no merge-commit policy_, meaning that when you encounter merge conflicts, you are expected to always rebase instead of merging. For example, -always use rebase when bringing the latest changes from the master branch to your feature branch. +always use rebase when bringing the latest changes from the `main` branch to your feature branch. If your PR contains merge commits, it will get marked as `has-merge-commits`. Once you have removed the merge commits, e.g., through an interactive rebase, you should remove the label again: @@ -328,7 +328,7 @@ the issue in question. However, if your PR fixes a stable-to-beta or stable-to-stable regression and has been accepted for a beta and/or stable backport (i.e., it is marked `beta-accepted` and/or `stable-accepted`), please do *not* use any such keywords since we don't -want the corresponding issue to get auto-closed once the fix lands on master. +want the corresponding issue to get auto-closed once the fix lands on `main`. Please update the PR description while still mentioning the issue somewhere. For example, you could write `Fixes (after beta backport) #NNN.`. diff --git a/src/external-repos.md b/src/external-repos.md index fb291aa77..6c38b3dc5 100644 --- a/src/external-repos.md +++ b/src/external-repos.md @@ -114,7 +114,7 @@ A `subtree pull` takes all changes since the last `subtree pull` from the tool repo and adds these commits to the rustc repo along with a merge commit that moves the tool changes into the specified directory in the Rust repository. -It is recommended that you always do a push first and get that merged to the tool master branch. +It is recommended that you always do a push first and get that merged to the tool `main`/`master` branch. Then, when you do a pull, the merge works without conflicts. While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to @@ -163,7 +163,7 @@ More information may be found on the Forge [Toolstate chapter]. In practice, it is very rare for documentation to have broken toolstate. Breakage is not allowed in the beta and stable channels, and must be addressed -before the PR is merged. They are also not allowed to be broken on master in +before the PR is merged. They are also not allowed to be broken on `main` in the week leading up to the beta cut. [git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules diff --git a/src/git.md b/src/git.md index 56f1f01f2..a01a156fa 100644 --- a/src/git.md +++ b/src/git.md @@ -57,9 +57,9 @@ useful when contributing to other repositories in the Rust project. Below is the normal procedure that you're likely to use for most minor changes 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 --ff-only`. + 1. Ensure that you're making your changes on top of `main`: + `git checkout main`. + 2. Get the latest changes from the Rust repo: `git pull upstream main --ff-only`. (see [No-Merge Policy][no-merge-policy] 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. @@ -72,7 +72,7 @@ and PRs: 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. [Open a PR][ghpullrequest] from your fork to `rust-lang/rust`'s master branch. + 7. [Open a PR][ghpullrequest] from your fork to `rust-lang/rust`'s `main` branch. [ghpullrequest]: https://guides.github.com/activities/forking/#making-a-pull-request @@ -101,7 +101,7 @@ Here are some common issues you might run into: Git has two ways to update your branch with the newest changes: merging and rebasing. Rust [uses rebasing][no-merge-policy]. If you make a merge commit, it's not too hard to fix: -`git rebase -i upstream/master`. +`git rebase -i upstream/main`. See [Rebasing](#rebasing) for more about rebasing. @@ -151,7 +151,7 @@ replace `src/tools/cargo` with the path to that submodule): - If you modified the submodule in several different commits, you will need to repeat steps 1-3 for each commit you modified. You'll know when to stop when the `git log` command shows a commit that's not authored by you. -5. Squash your changes into the existing commits: `git rebase --autosquash -i upstream/master` +5. Squash your changes into the existing commits: `git rebase --autosquash -i upstream/main` 6. [Push your changes](#standard-process). ### I see "error: cannot rebase" when I try to rebase @@ -197,7 +197,7 @@ and just want to get a clean copy of the repository back, you can use `git reset ```console # WARNING: this throws out any local changes you've made! Consider resolving the conflicts instead. -git reset --hard master +git reset --hard main ``` ### failed to push some refs @@ -222,12 +222,12 @@ rebase! Use `git push --force-with-lease` instead. If you see many commits in your rebase list, or merge commits, or commits by other people that you didn't write, it likely means you're trying to rebase over the wrong branch. For example, you may -have a `rust-lang/rust` remote `upstream`, but ran `git rebase origin/master` instead of `git rebase -upstream/master`. The fix is to abort the rebase and use the correct branch instead: +have a `rust-lang/rust` remote `upstream`, but ran `git rebase origin/main` instead of `git rebase +upstream/main`. The fix is to abort the rebase and use the correct branch instead: ```console git rebase --abort -git rebase -i upstream/master +git rebase -i upstream/main ```
Click here to see an example of rebasing over the wrong branch @@ -243,8 +243,8 @@ Git says you have modified some files that you have never edited. For example, running `git status` gives you something like (note the `new commits` mention): ```console -On branch master -Your branch is up to date with 'origin/master'. +On branch main +Your branch is up to date with 'origin/main'. Changes not staged for commit: (use "git add ..." to update what will be committed) @@ -277,11 +277,11 @@ merged. To do that, you need to rebase your work on top of rust-lang/rust. ### Rebasing -To rebase your feature branch on top of the newest version of the master branch +To rebase your feature branch on top of the newest version of the `main` branch of rust-lang/rust, checkout your branch, and then run this command: ```console -git pull --rebase https://github.com/rust-lang/rust.git master +git pull --rebase https://github.com/rust-lang/rust.git main ``` > If you are met with the following error: @@ -293,10 +293,10 @@ git pull --rebase https://github.com/rust-lang/rust.git master > case, run `git stash` before rebasing, and then `git stash pop` after you > have rebased and fixed all conflicts. -When you rebase a branch on master, all the changes on your branch are -reapplied to the most recent version of master. In other words, Git tries to -pretend that the changes you made to the old version of master were instead -made to the new version of master. During this process, you should expect to +When you rebase a branch on main, all the changes on your branch are +reapplied to the most recent version of `main`. In other words, Git tries to +pretend that the changes you made to the old version of `main` were instead +made to the new version of `main`. During this process, you should expect to encounter at least one "rebase conflict." This happens when Git's attempt to reapply the changes fails because your changes conflicted with other changes that have been made. You can tell that this happened because you'll see @@ -318,9 +318,9 @@ Your code This represents the lines in the file that Git could not figure out how to rebase. The section between `<<<<<<< HEAD` and `=======` has the code from -master, while the other side has your version of the code. You'll need to +`main`, while the other side has your version of the code. You'll need to decide how to deal with the conflict. You may want to keep your changes, -keep the changes on master, or combine the two. +keep the changes on `main`, or combine the two. Generally, resolving the conflict consists of two steps: First, fix the particular conflict. Edit the file to make the changes you want and remove the @@ -343,15 +343,15 @@ 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 +Using `git pull upstream main` while on your local `main` branch regularly will keep it up-to-date. You will also want to keep your feature branches up-to-date as well. After pulling, you can checkout the feature branches and rebase them: ```console -git checkout master -git pull upstream master --ff-only # to make certain there are no merge commits -git rebase master feature_branch +git checkout main +git pull upstream main --ff-only # to make certain there are no merge commits +git rebase main feature_branch git push --force-with-lease # (set origin to be the same as local) ``` @@ -360,7 +360,7 @@ To avoid merges as per the [No-Merge Policy](#no-merge-policy), you may want to to ensure that Git doesn't create merge commits when `git pull`ing, without needing to pass `--ff-only` or `--rebase` every time. -You can also `git push --force-with-lease` from master to double-check that your +You can also `git push --force-with-lease` from main to double-check that your feature branches are in sync with their state on the Github side. ## Advanced Rebasing @@ -373,14 +373,14 @@ On the one hand, you lose track of the steps in which changes were made, but the history becomes easier to work with. If there are no conflicts and you are just squashing to clean up the history, -use `git rebase --interactive --keep-base master`. This keeps the fork point +use `git rebase --interactive --keep-base main`. This keeps the fork point of your PR the same, making it easier to review the diff of what happened across your rebases. Squashing can also be useful as part of conflict resolution. If your branch contains multiple consecutive rewrites of the same code, or if the rebase conflicts are extremely severe, you can use -`git rebase --interactive master` to gain more control over the process. This +`git rebase --interactive main` to gain more control over the process. This allows you to choose to skip commits, edit the commits that you do not skip, change the order in which they are applied, or "squash" them into each other. @@ -388,8 +388,8 @@ Alternatively, you can sacrifice the commit history like this: ```console # squash all the changes into one commit so you only have to worry about conflicts once -git rebase -i --keep-base master # and squash all changes along the way -git rebase master +git rebase -i --keep-base main # and squash all changes along the way +git rebase main # fix all merge conflicts git rebase --continue ``` @@ -402,9 +402,9 @@ because they only represent "fixups" and not real changes. For example, After completing a rebase, and before pushing up your changes, you may want to review the changes between your old branch and your new one. You can do that -with `git range-diff master @{upstream} HEAD`. +with `git range-diff main @{upstream} HEAD`. -The first argument to `range-diff`, `master` in this case, is the base revision +The first argument to `range-diff`, `main` in this case, is the base revision that you're comparing your old and new branch against. The second argument is the old version of your branch; in this case, `@upstream` means the version that you've pushed to GitHub, which is the same as what people will see in your pull @@ -413,7 +413,7 @@ your branch; in this case, it is `HEAD`, which is the commit that is currently checked-out in your local repo. Note that you can also use the equivalent, abbreviated form `git range-diff -master @{u} HEAD`. +main @{u} HEAD`. Unlike in regular Git diffs, you'll see a `-` or `+` next to another `-` or `+` in the range-diff output. The marker on the left indicates a change between the @@ -481,7 +481,7 @@ to follow and understand. ### Hiding whitespace Github has a button for disabling whitespace changes that may be useful. -You can also use `git diff -w origin/master` to view changes locally. +You can also use `git diff -w origin/main` to view changes locally. ![hide whitespace](./img/github-whitespace-changes.png) diff --git a/src/tests/adding.md b/src/tests/adding.md index b02d8a0f0..ebbbb1cfc 100644 --- a/src/tests/adding.md +++ b/src/tests/adding.md @@ -1,7 +1,7 @@ # Adding new tests **In general, we expect every PR that fixes a bug in rustc to come accompanied -by a regression test of some kind.** This test should fail in master but pass +by a regression test of some kind.** This test should fail in `main` but pass after the PR. These tests are really useful for preventing us from repeating the mistakes of the past. diff --git a/src/tests/ci.md b/src/tests/ci.md index 5b6accec4..a30af309a 100644 --- a/src/tests/ci.md +++ b/src/tests/ci.md @@ -1,6 +1,6 @@ # Testing with CI -The primary goal of our CI system is to ensure that the `master` branch of +The primary goal of our CI system is to ensure that the `main` branch of `rust-lang/rust` is always in a valid state by passing our test suite. From a high-level point of view, when you open a pull request at @@ -16,7 +16,7 @@ From a high-level point of view, when you open a pull request at combines multiple PRs together, to reduce CI costs and merge delays. - Once the whole test suite finishes, two things can happen. Either CI fails with an error that needs to be addressed by the developer, or CI succeeds and - the merge commit is then pushed to the `master` branch. + the merge commit is then pushed to the `main` branch. If you want to modify what gets executed on CI, see [Modifying CI jobs](#modifying-ci-jobs). @@ -93,7 +93,7 @@ directly on the PR, in the "CI checks" section at the bottom of the PR page. ### Auto builds -Before a commit can be merged into the `master` branch, it needs to pass our complete test suite. +Before a commit can be merged into the `main` branch, it needs to pass our complete test suite. We call this an `auto` build. This build runs tens of CI jobs that exercise various tests across operating systems and targets. The full test suite is quite slow; @@ -169,10 +169,15 @@ the `@bors jobs=` parameter. The job pattern needs to match one or more jobs defined in the `auto` or `optional` sections of [`jobs.yml`]: -- `auto` jobs are executed before a commit is merged into the `master` branch. +- `auto` jobs are executed before a commit is merged into the `main` branch. - `optional` jobs are executed only when explicitly requested via a try build. They are typically used for tier 2 and tier 3 targets. +One reason to do a try build is to do a perf run, as described above, with `@rust-timer queue`. +This perf build then compares against some commit on main. +With `@bors try parent=` you can base your try build and subsequent perf run on a specific commit on `main`, +to help make the perf comparison as fair as possible. + > **Using `try-job` PR description directives** > > 1. Identify which set of try-jobs you would like to exercise. You can @@ -270,12 +275,12 @@ one or two should be sufficient in most cases. ## Merging PRs serially with bors CI services usually test the last commit of a branch merged with the last commit -in `master`, and while that’s great to check if the feature works in isolation, +in `main`, and while that’s great to check if the feature works in isolation, it doesn’t provide any guarantee the code is going to work once it’s merged. Breakages like these usually happen when another, incompatible PR is merged after the build happened. -To ensure a `master` branch that works all the time, we forbid manual merges. +To ensure a `main` branch that works all the time, we forbid manual merges. Instead, all PRs have to be approved through our bot, [bors] (the software behind it is called [homu]). All the approved PRs are put in a [merge queue] @@ -288,8 +293,8 @@ merge commit it wants to test to specific branches (like `auto` or `try`), which are configured to execute CI checks. Bors then detects the outcome of the build by listening for either Commit Statuses or Check Runs. Since the merge commit is -based on the latest `master` and only one can be tested at the same time, when -the results are green, `master` is fast-forwarded to that merge commit. +based on the latest `main` and only one can be tested at the same time, when +the results are green, `main` is fast-forwarded to that merge commit. Unfortunately, testing a single PR at a time, combined with our long CI (~2 hours for a full run), means we can’t merge a lot of PRs in a single day, and a @@ -359,7 +364,7 @@ caching], with the intermediate artifacts being stored on [ghcr.io]. We also push the built Docker images to ghcr, so that they can be reused by other tools (rustup) or by developers running the Docker build locally (to speed up their build). -Since we test multiple, diverged branches (`master`, `beta` and `stable`), we +Since we test multiple, diverged branches (`main`, `beta` and `stable`), we can’t rely on a single cache for the images, otherwise builds on a branch would override the cache for the others. Instead, we store the images under different