mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-27 19:00:11 +01:00
Jon MeowandChandler Carruth
f1e4323fda
Added here: - .pre-commit-config.yaml - docs/project/contribution_tools.md - src/scripts/pre-commit-toc.js - CONTRIBUTING.md - proposals/* (just to switch TOC formats) The rest consists of auto-generated fixes. The switch from doctoc to markdown-toc is because doctoc wants to put a TOC in every file, whereas markdown-toc only does it if you have an insertion point. Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
57 lines
2.5 KiB
Markdown
57 lines
2.5 KiB
Markdown
# Commenting guidelines
|
|
|
|
<!--
|
|
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
|
|
-->
|
|
|
|
These commenting guidelines are complementary to the
|
|
[evolution process](evolution.md). The community comments on proposals when the
|
|
proposal's status is "RFC", providing both positive and critical feedback. We
|
|
always try to keep feedback, even when critical, constructive and supportive.
|
|
|
|
## Guidelines
|
|
|
|
- **Comments should be specific about the issue.** They should include a
|
|
suggested action, and the expected result from that action. The more specific
|
|
a comment is, the easier it will be for the proposal author to evaluate.
|
|
|
|
- Objections to specific phrasing should suggest alternative phrasing.
|
|
|
|
- **Prefer GitHub for comments.** When reviewing a proposal, we would like to
|
|
keep the discussion focused in one place: the GitHub pull request.
|
|
|
|
- If your comment represents a significant change to the proposal, include a
|
|
list of pros and cons. Even if the author disagrees with the change, they
|
|
can use those to document the alternative.
|
|
- Feel free to extract long side discussions to a Discourse Forum topic, but
|
|
make sure any important conclusions or outcomes are reflected in either the
|
|
GitHub comments or the change itself.
|
|
|
|
- **Be supportive in your criticism.** The author may be receiving many
|
|
comments, and we want to keep contributors motivated to respond.
|
|
|
|
- **Be thoughtful about interactions.** Keep the
|
|
[code of conduct](/CODE_OF_CONDUCT.md) in mind. Try to understand
|
|
disagreements, and if you can't make progress, step back and think about other
|
|
possible approaches.
|
|
|
|
- **Compliment the author when you're happy with a proposal.** Especially on the
|
|
Discourse Forum topics where others will see the feedback. This helps all of
|
|
us avoid _only_ focusing on how proposals should improve. We want to balance
|
|
that important feedback with explicit and positive feedback for all the good
|
|
aspects.
|
|
|
|
When commenting on a proposal, some questions community members might want to
|
|
address are:
|
|
|
|
- What is your evaluation of the proposal?
|
|
- Is the problem being addressed significant enough to warrant a change to
|
|
Carbon?
|
|
- Does this proposal fit with Carbon's
|
|
[goals, priorities, and principles](goals.md)?
|
|
- Are there alternative approaches that may be better suited to the problem?
|
|
- If you have used other languages or libraries with a similar feature, how does
|
|
the proposal compare?
|