text

Author: danakj

proposals/p5270.md

@@ -16,55 +16,117 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -   [Problem](#problem)
 -   [Background](#background)
 -   [Proposal](#proposal)
--   [Details](#details)
 -   [Rationale](#rationale)
 -   [Alternatives considered](#alternatives-considered)
+    -   [Use a branch to refer to the explorer codebase](#use-a-branch-to-refer-to-the-explorer-codebase)
+    -   [Do nothing](#do-nothing)
 
 <!-- tocstop -->
 
 ## Abstract
 
-TODO: Describe, in a succinct paragraph, the gist of this document. This
-paragraph should be reproduced verbatim in the PR summary.
+The explorer codebase is no longer actively developed or maintained, but retains
+value as a place to look for implementations of various parts of the design.
+Having both the explorer and toolchain in the working git repository causes
+confusion for developers and users, and increases our incremental maintenance
+burden. We will move explorer out of the working git repository so that it
+remains accessible but is clearly deliniated from the toolchain and is more
+clearly frozen or archived.
 
 ## Problem
 
-TODO: What problem are you trying to solve? How important is that problem? Who
-is impacted by it?
+Users have expressed confusion when they come across examples or tests for the
+explorer that involve `Main()`, whereas the design and implementation of the
+toolchain have moved on to `Run()` as the entry point.
+
+Developers have attempted to update the explorer codebase to fix style guide
+issues[^1], as tools like grep or clang-tidy do not differentiate our active
+toolchain codebase from the frozen explorer one.
+
+As we update Bazel, Clang, Clang-tidy, etc, we also have to update the explorer
+codebase to keep it building cleanly.
+
+As we modify the `//testing` harness, we have to accommodate and work around the
+explorer tests[^2][^3][^4].
+
+[^1]: https://github.com/carbon-language/carbon-lang/pull/5224
+
+[^2]: https://github.com/carbon-language/carbon-lang/pull/4979
+
+[^3]: https://github.com/carbon-language/carbon-lang/pull/5025
+
+[^4]: https://github.com/carbon-language/carbon-lang/pull/5036
 
 ## Background
 
-TODO: Is there any background that readers should consider to fully understand
-this problem and your approach to solving it?
+-   Previous proposal:
+    [p3532: Focus implementation effort on the toolchain](https://github.com/carbon-language/carbon-lang/blob/trunk/proposals/p3532.md)
+-   Kick-off of this discussion
+    [#5224](https://github.com/carbon-language/carbon-lang/pull/5224#pullrequestreview-2730512195)
+-   Discord discussion:
+    [2025-04-02 #explorer](https://discord.com/channels/655572317891461132/763516049710120960/1356979197070803095)
 
 ## Proposal
 
-TODO: Briefly and at a high level, how do you propose to solve the problem? Why
-will that in fact solve it?
-
-## Details
+1. Add a tag `explorer-archived` in the main `carbon-lang` git repository.
+2. Copy the `//explorer` directory and its dependencies to a new `explorer`
+   repository under the `carbon-language` organization.
+3. Locally ensure the explorer tests build and pass under the `explorer`
+   repository.
+4. Add a `README.md` to the `explorer` repository that explains explorer is
+   archived and not under active development.
+5. Delete `//explorer` in the main `carbon-lang` repository.
 
-TODO: Fully explain the details of the proposed solution.
+Note that fuzzer test cases from the explorer are already relocated under
+`//toolchain/*/fuzzer_corpus/`.
 
 ## Rationale
 
-TODO: How does this proposal effectively advance Carbon's goals? Rather than
-re-stating the full motivation, this should connect that motivation back to
-Carbon's stated goals and principles. This may evolve during review. Use links
-to appropriate sections of [`/docs/project/goals.md`](/docs/project/goals.md),
-and/or to documents in [`/docs/project/principles`](/docs/project/principles).
-For example:
-
--   [Community and culture](/docs/project/goals.md#community-and-culture)
--   [Language tools and ecosystem](/docs/project/goals.md#language-tools-and-ecosystem)
--   [Performance-critical software](/docs/project/goals.md#performance-critical-software)
--   [Software and language evolution](/docs/project/goals.md#software-and-language-evolution)
--   [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write)
--   [Practical safety and testing mechanisms](/docs/project/goals.md#practical-safety-and-testing-mechanisms)
--   [Fast and scalable development](/docs/project/goals.md#fast-and-scalable-development)
--   [Modern OS platforms, hardware architectures, and environments](/docs/project/goals.md#modern-os-platforms-hardware-architectures-and-environments)
--   [Interoperability with and migration from existing C++ code](/docs/project/goals.md#interoperability-with-and-migration-from-existing-c-code)
+The primary purpose of the explorer codebase at this time is as a demonstration
+of past work implementing the carbon language design. This can help to inform
+the implementation of the toolchain as it catches up in various areas, as long
+as the design has not deviated from the explorer implementation.
+
+Searching in, and providing links to the explorer codebase comes up in design
+discussions occasionally [^5], and we should maintain the ability of toolchain
+developers to look through the explorer easily. The primary place they do so is
+on github, where the code can be linked to. Github search only works
+[on the main branch](https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax#using-qualifiers)
+of a repository, so the `trunk` branch for the `carbon-lang` repository. To
+maintain searchability, the explorer codebase must either remain on `trunk` in
+`carbon-lang` or in a sibling repository.
+
+Proposal
+[p3532](https://github.com/carbon-language/carbon-lang/blob/trunk/proposals/p3532.md)
+directed to keep the explorer codebase active in the main repository, with its
+tests building and running:
+
+> We should keep the Explorer's code in place, building, and passing its basic
+> regression tests because the built artifacts of the Explorer remain really
+> valuable given its coverage of our design's feature sets.
+
+However the [problems](#problem) discussed above result from this situation. We
+can gain the benefit of access to the codebase while reducing its impact on
+developers and users by moving it into a separate git repository.
+
+[^5]:
+    https://discord.com/channels/655572317891461132/941071822756143115/1349523309682753606
 
 ## Alternatives considered
 
-TODO: What alternative solutions have you considered?
+### Use a branch to refer to the explorer codebase
+
+We could create a branch in the `carbon-lang` repository that contains explorer,
+but delete it from `trunk`. This would also allow the code to be found and
+linked to, however GitHub search does not support searching in a branch. The
+main purpose of the explorer code while archived is for reading the
+implementation, and search is an important part of that.
+
+### Do nothing
+
+If, in the future, we want to restart development of the explorer codebase, we
+will benefit from keeping the codebase building as we upgrade Bazel, Clang,
+Clang-tidy, etc. However we don't currently have the resources to build two
+implementations of the language, and there's no plan in our roadmaps to restart
+explorer development. So the cost of letting the explorer codebase become stale
+is outweighed by the costs of keeping it active.