TODO Comments, Crates.io, PR Structure and Naming Conventions

variants are added to the enum, they may not get handled correctly. Ask yourself: if a new variant were added to this enum, what's the chance that it would want to use the `_` code, versus having some other treatment? Unless the answer is "low", then prefer an exhaustive match. The same advice applies to `if let` and `while let`, which are effectively tests for a single variant. ### Use "TODO" comments for things you don't want to forget As a useful tool to yourself, you can insert a `// TODO` comment for something that you want to get back to before you land your PR: ```rust,ignore fn do_something() { if something_else { unimplemented!(); // TODO write this } } ``` The tidy script will report an error for a `// TODO` comment, so this code would not be able to land until the TODO is fixed (or removed). This can also be useful in a PR as a way to signal from one commit that you are leaving a bug that a later commit will fix: ```rust,ignore if foo { return true; // TODO wrong, but will be fixed in a later commit } ``` <a id="cio"></a> ## Using crates from crates.io See the [crates.io dependencies][crates] section. <a id="er"></a> ## How to structure your PR How you prepare the commits in your PR can make a big difference for the reviewer. Here are some tips. **Isolate "pure refactorings" into their own commit.** For example, if you rename a method, then put that rename into its own commit, along with the renames of all the uses. **More commits is usually better.** If you are doing a large change, it's almost always better to break it up into smaller steps that can be independently understood. The one thing to be aware of is that if you introduce some code following one strategy, then change it dramatically (versus adding to it) in a later commit, that 'back-and-forth' can be confusing. **Format liberally.** While only the final commit of a PR must be correctly formatted, it is both easier to review and less noisy to format each commit individually using `./x fmt`. **No merges.** We do not allow merge commits into our history, other than those by bors. If you get a merge conflict, rebase instead via a command like `git rebase -i rust-lang/master` (presuming you use the name `rust-lang` for your remote). **Individual commits do not have to build (but it's nice).** We do not require that every intermediate commit successfully builds – we only expect to be able to bisect at a PR level. However, if you *can* make individual commits build, that is always helpful. ## Naming conventions Apart from normal Rust style/naming conventions, there are also some specific to the compiler. - `cx` tends to be short for "context" and is often used as a suffix. For example, `tcx` is a common name for the [Typing Context][tcx]. - [`'tcx`][tcx] is used as the lifetime name for the Typing Context. - Because `crate` is a keyword, if you need a variable to represent something crate-related, often the spelling is changed to `krate`.

This section covers using `// TODO` comments to mark unfinished code that the tidy script will flag, linking to the crates.io dependencies documentation, structuring PRs by isolating refactorings, breaking changes into smaller commits, formatting each commit, avoiding merge commits (rebasing instead), and adhering to naming conventions. Key conventions include using `cx` for "context" (e.g., `tcx` for Typing Context), `'tcx` for the Typing Context lifetime, and `krate` instead of `crate` when referring to crate-related variables.