mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-27 10:00:09 +01:00
David Sankel
ea0a37dbf3
Reading through extensive problem and background documentation before seeing what is being proposed is tedious for a reader. An abstract section at the beginning of a document that provides a succinct summary helps a lot. We propose adding such a section to our proposal template.
88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# TODO
|
|
|
|
<!--
|
|
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
|
|
-->
|
|
|
|
[Pull request](https://github.com/carbon-language/carbon-lang/pull/####)
|
|
|
|
<!-- toc -->
|
|
|
|
## Table of contents
|
|
|
|
- [TODO: Initial proposal setup](#todo-initial-proposal-setup)
|
|
- [Abstract](#abstract)
|
|
- [Problem](#problem)
|
|
- [Background](#background)
|
|
- [Proposal](#proposal)
|
|
- [Details](#details)
|
|
- [Rationale](#rationale)
|
|
- [Alternatives considered](#alternatives-considered)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## TODO: Initial proposal setup
|
|
|
|
> TIP: Run `./new_proposal.py "TITLE"` to do new proposal setup.
|
|
|
|
1. Copy this template to `new.md`, and create a commit.
|
|
2. Create a GitHub pull request, to get a pull request number.
|
|
- Add the `proposal draft` label to the pull request.
|
|
3. Rename `new.md` to `/proposals/p####.md`, where `####` should be the pull
|
|
request number.
|
|
4. Update the title of the proposal (the `TODO` on line 1).
|
|
5. Update the link to the pull request (the `####` on line 11).
|
|
6. Delete this section.
|
|
|
|
TODOs indicate where content should be updated for a proposal. See
|
|
[Carbon Governance and Evolution](/docs/project/evolution.md) for more details.
|
|
|
|
## Abstract
|
|
|
|
TODO: Describe, in a succinct paragraph, the gist of this document. This
|
|
paragraph should be reproduced verbatim in the PR summary.
|
|
|
|
## Problem
|
|
|
|
TODO: What problem are you trying to solve? How important is that problem? Who
|
|
is impacted by it?
|
|
|
|
## Background
|
|
|
|
TODO: Is there any background that readers should consider to fully understand
|
|
this problem and your approach to solving it?
|
|
|
|
## Proposal
|
|
|
|
TODO: Briefly and at a high level, how do you propose to solve the problem? Why
|
|
will that in fact solve it?
|
|
|
|
## Details
|
|
|
|
TODO: Fully explain the details of the proposed solution.
|
|
|
|
## 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)
|
|
|
|
## Alternatives considered
|
|
|
|
TODO: What alternative solutions have you considered?
|