It takes a bit of work to track down instructions on running file tests
and autoupdate. Add a link to them directly from CONTRIBUTING.md, since
all searches start there.
The goal is to clarify that tool-generated submissions are fine, but
emphasize the requirements we have on the operators of these tools. The
inspiration for the two aspects emphasized comes from the discussion
around an update to LLVM's policy in
https://github.com/llvm/llvm-project/pull/154441, and in Fedora's
policy:
https://docs.fedoraproject.org/en-US/council/policy/ai-contribution-policy/
I've not used those policies _exactly_, as I think we may want somewhat
simpler and less formal guidance, but the goal is to remain
directionally aligned.
That said, I'm not attached to the current iteration of the wording, it
still feels a bit excessively formal or wordy to me. Suggestions on
wording improvements very welcome in addition to thoughts and feedback
on the overall direction.
---------
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Co-authored-by: Dana Jansens <danakj@orodu.net>
Co-authored-by: Carbon Infra Bot <carbon-external-infra@google.com>
Establish some guidance on using AI coding tools when contributing to
the Carbon
Language project. These tools have growing popularity and interest, and
it would
be good to have a clear and actively documented set of guidance for
folks
interested or already using them.
---------
Co-authored-by: Jon Ross-Perkins <jperkins@google.com>
These docs do not seem to be the standard entries anymore given than
it's been 2 years since they were used.
---------
Co-authored-by: Jon Ross-Perkins <jperkins@google.com>
Co-authored-by: Carbon Infra Bot <carbon-external-infra@google.com>
Proposal to focus implementation effort for the next 1-2 years on the
Carbon
toolchain instead of the explorer. This will impact the explorer in a
few ways:
- We will keep the explorer's code in place, building, and passing its
basic
tests. It can remain a good baseline for exploring Carbon's language
features.
- We won't prioritize expanding the explorer's coverage of Carbon
features or
other improvements -- it is good enough for what we need until the
toolchain
catches up.
- We will stop actively fuzzing and expanding test coverage for the
explorer.
- Eventually, when we want to resume work on the explorer, we'll
evaluate the
best platform to build on -- the current explorer codebase or on top of
the
toolchain's semantic IR.
Also tries to update the core readme and contributing docs to reflect
this.
Key rewrite points:
- Making more use of apt now, since we no longer need `brew` for llvm on Linux.
- Gets ahead of issues with brew's llvm 15 on Linux.
- Clear list of commands for a typical setup.
- Less verbose text about various tool options (I think this was just too much).
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
This is being done because Projects v1 requires repo write access, a serious limitation for letting people use it. Projects v2 isn't a great option because it lacks event support. Labels are pretty stable in GitHub, so this switches to that.
Note this assumes we're fine renaming "decision: accepted" -> "proposal accepted", etc. There are two reasons for this:
1) To make it clear that this is a proposal-specific label, versus something like an issue for leads label.
2) Removing the colon because it was causing trouble with yaml syntax.
This also adds the "proposal draft" label, mainly to complete the taxonomy.
I was considering whether this should be a proposal itself, but it feels like maybe it's not necessary because it's a fairly low-key infrastructure change, and I'm not sure how much people were relying on the project board anyways.
I tested this in a personal repo, basically just poking at https://github.com/jonmeow/test/pull/2
Part of #1902Fixes#1904
Regarding #1904, using #access-requests because I've decided I feel weird using any other channel for this (including #proposal-prs-and-process)
- Generally replace Discourse mentions with GitHub Discussions, per #444
- Switch from "Discord Chat" to just "Discord" because there's no more ambiguity, and "Discord" is the more common term.
- Fix mentions of "core team" to "Carbon leads" (because the touched docs overlap a lot).
Co-authored-by: Matthew Riley <mdriley@gmail.com>
Just a minor refresh, and trying to make the contribution tools link a bit more general (I'll be updating that separately, but it's already more generic than indicated).
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.
* Proposal for an explicit GitHub workflow.
This suggests a GitHub workflow that uses pull requests, produces linear
history, and both incentivizes and encourages small, incremental changes
(both at the pull request and commit granularity). It tries to follow
general best practices around software engineering at scale and GitHub
workflows. It also tries to ensure the workflow is very well supported
by tooling and automation built into GitHub.
Of note, this proposal should match precisely the current enforced flow
on our GitHub repositories. But we need to actually decide we like this,
write up the rationale behind it, and document what we're doing.
I've added an abbreviated version of the proposal as a documentation
update to the contributing file. Happy to restructure or find a better
home for this. I've tried to focus on the parts that contributors
actually would need to care about as opposed to the things that are
simply and fully enforced mechanically.
My hope after this is to suggest more detailed code review guidelines.
* Addressing review comments.
Notably, I really was giving too much weight to multi-commit PRs which
shouldn't be the common or default. I've tried to restructure everything
to make it much more clear what is going on here.
* Minor tweaks
* Fix typo in CONTRIBUTING.md
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
* Extract workflow description and remove redundancies.
* remove tracking issue template field
* Update proposals/p0029.md with reviewer suggsetion.
Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>
* Continue to address review feedback.
* Apply suggestions from code review
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Co-authored-by: austern <austern@google.com>
* Incorporate code review feedback and begin moving toward "trunk" based terminology
* Tweak the wording and make it a bit more consistent.
* Update docs/project/pull_request_workflow.md
Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>
* Address more review comments.
* Correct the rationale.
* Tweak wording based on discussion in review.
* Improve the rationale around the default branch to avoid overstating or
misstatig things.
* Apply suggestions from code review
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
* Clean up formatting and address a couple of comments on grammar from review.
* Update docs/project/pull_request_workflow.md
Co-authored-by: austern <austern@google.com>
* Add to proposal list.
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>
Co-authored-by: Jon Meow <46229924+jonmeow@users.noreply.github.com>
Co-authored-by: austern <austern@google.com>
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>
The original header was exactly 80-columns which made every file format
with a line-start comment syntax reflow the text. Instead, pick
a canonical re-flowing that keeps it to just three lines. This also lets
the text refer to the project which seems more clear.
No practical or semantic change here, just getting consistent wording
and line breaks for regularity.
CONTRIBUTING.md replaces the mention of Google style guide (which isn't automated) with Prettier (which should do most of the hauling). The rest is the formatter.
Dana Jansens
Jon Ross-Perkins
Richard Smith
Nicholas Bishop
Krishna Agarwal
MarchMore
Ethan Havemann
Josh Soref
Jon MeowandMatthew Riley
Bryce Adelstein Lelbach aka wash
