Merge branch 'main' into few_args

Author: bricknerb

.github/workflows/auto_assign_prs.yaml

@@ -0,0 +1,24 @@
+# Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+# Exceptions. See /LICENSE for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+# This file is only used for PR autoassignment. Branch protections don't enforce
+# it.
+#
+# Syntax:
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-syntax
+
+# Toolchain reviewers are used as a fallback.
+*                          @carbon-language/toolchain-reviewers
+
+# Key project documents should be reviewed by leads.
+/*.md                      @carbon-language/leads
+/LICENSE                   @carbon-language/leads
+/docs/project/evolution.md @carbon-language/leads
+/docs/project/goals.md     @carbon-language/leads
+/docs/project/principles/* @carbon-language/leads
+/docs/project/roadmap.md   @carbon-language/leads
+/proposals/*.md            @carbon-language/leads
+
+# Toolchain code.
+/toolchain                 @carbon-language/toolchain-reviewers

CODEOWNERS

@@ -862,6 +862,9 @@ or restrictions on casts between pointers and integers.
 
 ### Arrays and slices
 
+> **TODO:** The provisional array syntax documented here has been superseded by
+> [p4682: The Core.Array type for direct-storage immutably-sized buffers](/proposals/p4682.md).
+
 The type of an array of holding 4 `i32` values is written `[i32; 4]`. There is
 an [implicit conversion](expressions/implicit_conversions.md) from tuples to
 arrays of the same length as long as every component of the tuple may be

docs/design/README.md

@@ -752,6 +752,10 @@ class GraphNode {
 **Open question:** What is specifically allowed and forbidden with an incomplete
 type has not yet been decided.
 
+> **TODO:** Document that qualified names can be looked up in an incomplete
+> type, as adopted in
+> [p5087: Qualified lookup into types being defined](/proposals/p5087.md).
+
 ### `Self`
 
 A `class` definition may provisionally include references to its own name in

docs/design/classes.md

@@ -33,6 +33,12 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Overview
 
+> **TODO:** [p3720: Member binding operators](/proposals/p3720.md) introduces an
+> additional "member binding" step, redefines simple member access in terms of
+> compound member access, and defines compound member access in terms of calls
+> to user-implementable interface methods. This document must be updated to
+> reflect those changes.
+
 A _qualified name_ is a [word](../lexical_conventions/words.md) that is preceded
 by a period or a rightward arrow. The name is found within a contextually
 determined entity:

docs/design/expressions/member_access.md

@@ -24,6 +24,13 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Overview
 
+> **TODO:** Update this document to reflect the introduction of function values,
+> function types, and the `Call` interface in
+> [p2875: Functions, function types, and function calls](/proposals/p2875.md).
+
+> **TODO:** Update this document to reflect the changes to named functions in
+> [p3848: Lambdas](/proposals/p3848.md).
+
 Functions are the core building block for applications. Carbon's basic function
 syntax is:
 

docs/design/functions.md

@@ -447,6 +447,10 @@ impl Point_ExtendForward as Vector {
 }
 ```
 
+> **TODO:** The second `impl` in this example is no longer a valid redeclaration
+> of the first after
+> [p5366: The name of an `impl` in `class` scope](/proposals/p5366.md).
+
 More about forward declaring implementations in
 [its dedicated section](#declaring-implementations).
 
@@ -929,6 +933,9 @@ constraint DrawVectorLegoFish {
 }
 ```
 
+> **TODO:** Document that `Self` can be omitted, as adopted in
+> [P5337: Interface extension and `final impl` update](/proposals/p5337.md).
+
 In general, Carbon makes no syntactic distinction between the uses of named
 constraints and interfaces, so one may be replaced with the other without
 affecting users. To accomplish this, Carbon allows a named constraint to be used
@@ -1249,6 +1256,10 @@ fn DoHashAndEquals[T:! Hashable](x: T) {
 
 ### Interface extension
 
+> **TODO:** Update this section as needed to reflect the fact that an impl of an
+> interface doesn't impl the interfaces it extends, as adopted in
+> [p5168: Forward `impl` declaration of an incomplete interface](/proposals/p5168.md).
+
 When implementing an interface, we allow implementing the aliased names as well.
 In the case of `Hashable` above, this includes all the members of `Equatable`,
 obviating the need to implement `Equatable` itself:
@@ -1276,6 +1287,9 @@ benefits:
 We expect this concept to be common enough to warrant dedicated `interface`
 syntax:
 
+> **TODO:** Update this section to reflect the new syntax adopted in
+> [p5337: Interface extension and `final impl` update](/proposals/p5337.md).
+
 ```carbon
 interface Equatable { fn Equals[self: Self](rhs: Self) -> bool; }
 
@@ -1326,6 +1340,9 @@ interface SetAlgebra {
 }
 ```
 
+> **TODO:** Document `extend [final] impl as I`, as adopted in
+> [p5337: Interface extension and `final impl` update](/proposals/p5337.md).
+
 **Alternative considered:** The `extend` declarations are in the body of the
 `interface` definition instead of the header so we can use
 [associated constants](terminology.md#associated-entity) also defined in the
@@ -1434,6 +1451,9 @@ interface MovieCodec {
 
 #### Diamond dependency issue
 
+> **TODO:** Update this section to reflect the changes in
+> [p5168: Forward `impl` declaration of an incomplete interface](/proposals/p5168.md).
+
 Consider this set of interfaces, simplified from
 [this example generic graph library doc](https://docs.google.com/document/d/15Brjv8NO_96jseSesqer5HbghqSTJICJ_fTaZOH0Mg4/edit?usp=sharing&resourcekey=0-CYSbd6-xF8vYHv9m1rolEQ):
 
@@ -1986,6 +2006,10 @@ keyword `private` before `adapt`, so you might write
 
 ## Associated constants
 
+> **TODO:** Update this section to reflect the new rules and guidance on
+> associated constants in
+> [p5168: Forward `impl` declaration of an incomplete interface](/proposals/p5168.md).
+
 In addition to associated methods, we allow other kinds of
 [associated entities](terminology.md#associated-entity). For consistency, we use
 the same syntax to describe a compile-time constant in an interface as in a type
@@ -2112,6 +2136,10 @@ Together associated methods and associated class functions are called
 _associated functions_, much like together methods and class functions are
 called [member functions](/docs/design/classes.md#member-functions).
 
+> **TODO:** Document rules on where associated function implementations can be
+> declared, as adopted in
+> [p5168: Forward `impl` declaration of an incomplete interface](/proposals/p5168.md).
+
 ## Associated facets
 
 Associated facets are [associated constants](#associated-constants) that happen
@@ -4466,6 +4494,9 @@ difference.
 
 #### Prioritization rule
 
+> **TODO:** Document the changes to prioritization adopted in
+> [p5337: Interface extension and `final impl` update](/proposals/p5337.md).
+
 Since at most one library can contain `impl` definitions with a given type
 structure, all `impl` definitions with a given type structure must be in the
 same library. Furthermore by the [`impl` declaration access rules](#access),
@@ -4864,6 +4895,10 @@ class Optional(T:! type) {
 // ❌ Illegal: impl Optional(i32) as Deref { ... }
 ```
 
+> **TODO:** Update the following passage to reflect the relaxed overlap rule
+> adopted in
+> [p5337: Interface extension and `final impl` update](/proposals/p5337.md).
+
 This prevents any higher-priority impl that overlaps a final impl from being
 defined unless it agrees with the `final` impl on the overlap. Overlap is
 computed between two non-`template` `impl` declaration by
@@ -4996,6 +5031,10 @@ differences between the Carbon design and Rust plans:
 
 ## Forward declarations and cyclic references
 
+> **TODO:** Update this section to distinguish between _defined_ and _complete_,
+> as adopted in
+> [p5087: Qualified lookup into types being defined](/proposals/p5087.md).
+
 Interfaces, named constraints, and their implementations may be forward declared
 and then later defined. This is needed to allow cyclic references, for example
 when declaring the edges and nodes of a graph. It is also a tool that may be
@@ -5014,6 +5053,10 @@ used.
 
 ### Declaring interfaces and named constraints
 
+> **TODO:** Update this section to reflect the additional things you can do with
+> a defined but incomplete type, as adoped in
+> [p5087: Qualified lookup into types being defined](/proposals/p5087.md).
+
 The declaration for an interface or named constraint consists of:
 
 -   an optional access-control keyword like `private`,
@@ -5100,6 +5143,9 @@ An incomplete `C` cannot be used in the following contexts:
 
 ### Declaring implementations
 
+> **TODO:** Update this section to reflect the new rules adopted in
+> [p5168: Forward `impl` declaration of an incomplete interface](/proposals/p5168.md).
+
 The declaration of an interface implementation consists of:
 
 -   optional modifier keyword `final`,
@@ -5115,6 +5161,9 @@ The declaration of an interface implementation consists of:
     [associated constants](#associated-constants) including
     [associated facets](#associated-facets).
 
+> **TODO:** Document the redeclaration syntax `impl C.(as I)` adopted in
+> [p5366: The name of an `impl` in `class` scope](/proposals/p5366.md).
+
 **Note:** The type before the `as` is required except in class scope, where it
 defaults to `Self` as described in the
 [matching and agreeing section](#matching-and-agreeing).
@@ -5154,6 +5203,11 @@ these rules:
 
 ### Matching and agreeing
 
+> **TODO:** Update this section to reflect the new terminology and rules adopted
+> in [p3763: Matching redeclarations](/proposals/p3763.md), and the new rules
+> adopted in
+> [p5168: Forward `impl` declaration of an incomplete interface](/proposals/p5168.md).
+
 Carbon needs to determine if two declarations match in order to say which
 definition a forward declaration corresponds to and to verify that nothing is
 defined twice. Declarations that match must also agree, meaning they are
@@ -5189,6 +5243,10 @@ expressions match along with
     an interface, as in `constraint Equivalent { extend MyInterface; }`, is not
     considered to match.
 
+> **TODO:** Document the matching rules for the redeclaration syntax
+> `impl C.(as I)` adopted in
+> [p5366: The name of an `impl` in `class` scope](/proposals/p5366.md).
+
 For implementations to agree:
 
 -   The presence of the modifier keyword `final` before `impl` must match

docs/design/generics/details.md

@@ -28,6 +28,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     -   [What should be covered by a review?](#what-should-be-covered-by-a-review)
     -   [Writing review comments](#writing-review-comments)
     -   [Approving the change](#approving-the-change)
+    -   [Pausing reviews and reassigning PRs](#pausing-reviews-and-reassigning-prs)
 -   [Merging pull requests](#merging-pull-requests)
     -   [Merge commit descriptions](#merge-commit-descriptions)
 -   [Resolving an impasse or conflict](#resolving-an-impasse-or-conflict)
@@ -86,11 +87,11 @@ In Carbon, developers will focus on particular areas, loosely broken down as:
     -   We split out auto-assignment by explorer, toolchain, and other files
         (including documentation).
 
-[Auto-assignment](/.github/workflows/auto_assign_prs.yaml) will help find
-owners, but won't always be perfect -- developers may take a PR they weren't
-auto-assigned in order to help review go quickly. Contributors can also request
-multiple reviewers, but it can be daunting to get feedback from a large number
-of reviewers, so we suggest keeping the number of reviewers reasonably small.
+[Auto-assignment](/CODEOWNERS) will help find owners, but won't always be
+perfect -- developers may take a PR they weren't auto-assigned in order to help
+review go quickly. Contributors can also request multiple reviewers, but it can
+be daunting to get feedback from a large number of reviewers, so we suggest
+keeping the number of reviewers reasonably small.
 
 Any reviews that explicitly request changes should be addressed, either with the
 changes or an explanation of why not, before a pull request is merged. Further,
@@ -440,6 +441,18 @@ author can always come back to you if they have questions, and we can always
 revert changes if the resolution for some reason diverges wildly from your
 expectations.
 
+### Pausing reviews and reassigning PRs
+
+When temporarily unavailable to review, for example due to a vacation, reviewers
+can either mark themselves as
+[busy in GitHub](https://docs.github.com/en/account-and-profile/tutorials/personalize-your-profile#setting-a-status),
+or ask an admin to stop assignment (using
+["Never assign to certain team members"](https://docs.github.com/en/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team#configuring-auto-assignment)).
+
+A PR's reviewer can also be changed to a team, such as
+`carbon-language/toolchain-reviewers`, and it should be automatically
+reassigned. This can be done by anyone, not just a reviewer.
+
 ## Merging pull requests
 
 Pull requests are ready to be merged when reviewers have indicated they're happy

docs/project/code_review.md

@@ -314,9 +314,36 @@ The author of a proposal is not required to include changes to the design
 documentation as part of a proposal, and it may in some cases be preferable to
 decouple the proposal process from updating the design. When accepted, the
 proposal would then be implemented through a series of future PRs to the rest of
-the project, and the proposal document should describe what is being proposed in
-enough detail to validate that those future PRs properly implement the proposed
-direction.
+the project. If the proposal PR defers any documentation changes in this way,
+the proposal document should describe what is being proposed in enough detail to
+validate that those future PRs properly implement the proposed direction, and
+the proposal PR should add "TODO" comments in the places where significant
+future changes will be needed (including adding new placeholder documents if
+needed), with links back to the proposal document. These comments should be kept
+close to the passages that need to be changed. This is intended to ensure that
+readers of the design documentation know when what they're reading is out of
+date, and can easily find out what has changed. For example:
+
+```md
+> **TODO:** Document the redeclaration syntax `impl C.(as I)` adopted in
+> [p5366](/proposals/p5366.md).
+```
+
+See the `docs/design` changes in
+[#5606: Keep design documents current](https://github.com/carbon-language/carbon-lang/pull/5606)
+for additional examples of adding those comments. As with other parts of the
+proposal, these comments should be included in the initial PR, and updated as
+needed during the review.
+
+As an exception, proposals that will have a widespread, pervasive effect on the
+design documents (such as proposals to replace widely-used vocabulary) usually
+shouldn't make those changes as part of the proposal, so that changes during the
+review aren't an excessive burden on the proposal author. Such proposals usually
+shouldn't apply "TODO" comments either, because pervasive "TODO" comments are
+more likely to be disruptive than helpful to the reader. Instead, the proposal
+author should file a GitHub issue to track the need for documentation updates,
+and include a link to it in the proposal document, and then follow up with pull
+requests to make the changes after the proposal is approved by the leads.
 
 #### Open questions