mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-09-28 22:02:37 +01:00
Jon Meow
be116a46c9
We're running into issues with md handlers that expect this kind of 4-space indent. It should be cross-compatible with GH, so switch, even though it feels a little churny.
Manual edits are to:
- .prettierrc.yaml:
- rename from .prettierrc
- add tabWidth (primary change)
- add trailingComma (fix vimPrettier skew)
- contribution_tools.md: Fix remarks about .prettierrc.yaml
- pre-commit-toc.js: indent, bullets
- pre-commit-proposal-list.py: indent of output
The rest is the result of `pre-commit run --all-files`
Unfortunately this'll probably depend on the change being propagated into PR branches, so I wouldn't be surprised if we see regressions for a bit. We'll also need to nudge people to update .vimrc's. Hopefully the pre-commit GH action helps catch issues.
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 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?
|