mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-11-18 18:00:29 +00:00
With one manual ignore in the markdown style proposal, because it's explicitly listing disallowed terms.
58 lines
2.6 KiB
Markdown
58 lines
2.6 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 advantages and disadvantages. 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?
|