Update contribution text. (#11)

csyonghe · web-flow · commit c3d8a5f84da3 · 2024-11-12T20:23:05.000-08:00
diff --git a/community/become-a-committer.md b/community/become-a-committer.md
@@ -40,7 +40,7 @@ Consistent quality and dedication are key criteria. Committers typically have:
 
 ## The Committer Nomination Process
 
-Once you meet the criteria above, you can nominate yourself to become a committer. This process includes:
+Once you meet the criteria above, you can request to be nominated to become a committer. This process includes:
 
 **Nomination:** You can ask a committer to nominate you to become a committer via our discord channel.
 
diff --git a/community/code-quality.md b/community/code-quality.md
@@ -5,7 +5,7 @@ Thank you for your interest in contributing to Slang! We welcome contributions f
 
 **Follow Project Standards:** Adhere to the code style and conventions currently used in Slang. This includes formatting, naming conventions, and structural patterns.
 
-**Consistent Formatting:** Use spaces/tabs, line lengths, and other formatting elements as defined by the existing code. All code must be formatted with `clang-format` using the configuration in root directory.
+**Consistent Formatting:** Use spaces/tabs, line lengths, and other formatting elements as defined by the existing code. All code must be formatted with `clang-format` using the configuration in the root source directory.
 
 **Comments and Documentation:** Document all public methods, significant logic blocks, and any complex code in a clear, concise manner. Each comment should add value to the code and explain why something is done, not just what it does.
 
diff --git a/community/index.md b/community/index.md
@@ -10,40 +10,44 @@ We use the [GitHub discussion page](https://github.com/shader-slang/slang/discus
 
 ## Community Structure
 
-We distinguish in our community between “community”, “committer” and OWNERs in our system inspired by eg. [Chromium](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/code_reviews.md#expectations-of-owners).
+We distinguish in our community between "Community Member", "Committer" and "Owners".
 
 #### Community Member
 
-The term community refers to everyone using Slang or participating in the Slang open source project in any form. All community members are welcomed to
+The term community refers to everyone using Slang or participating in the Slang open source project in any form. All community members are welcome to
 report issues, start discussion threads, or submit pull requests.
 
 #### Committer
 
-A committer is a community member who has write access to the Slang repository and can approve pull requests. This is a status that can be earned by maintaining a track record of submiting and landing code changes to the Slang project. All community members can review code submitted by other community members, but for a pull request to be considered approved and ready for merging, at least one **owner** (more info below) of each file you are touching must provide an approving review. Ideally a committer should choose reviewers who are familiar with the area of code you are touching. If you have doubts, look at the git blame for the file and the OWNERS files.
+A committer is a community member who has write access to the Slang repository and can approve pull requests. This is a status that can be earned by maintaining a track record of submitting and landing code changes to the Slang project (see more details on [the process of becoming a committer](/community/become-a-committer).) All community members can review code submitted by other community members, but for a pull request to be considered approved and ready for merging, at least one **owner** (more info below) of each file you are touching must provide an approving review. Ideally a committer should choose reviewers who are familiar with the area of code you are touching. If you have doubts, look at the git blame for the file and the OWNERS files.
 
-Submissions to a repository by a change contributor who is not a Slang committer require two committers to approve the submission. If the author of the pull request is already a committer, then only one other committer is needed to review.
+Submissions to `docs/proposals` are considered **Slang Proposed Features (SPFs)**, and require two *Language Owners* (more info below) to approve the submission.
 
 #### Owner
 
-Every file in the Slang repository has a list of owners. An owner of a directory has right to approve pull requests touching the directory. A pull request is approved only when at least two owners of each directory affected by the changes have given their approval. If you are a committer and think you’re ready to become an owner of a directory, put up a PR to the relevant OWNERs and get two owners to review it. In face of conflict between owner, owner need to reach consensus amongst themselves.
+Every file in the Slang repository has a list of owners. An owner of a directory has the right to approve pull requests touching the directory. A pull request is approved only when at least two owners of each directory affected by the changes have given their approval. If you are a committer and think you’re ready to become an owner of a directory, put up a PR to the relevant OWNERs and get two owners to review it. In case of conflict between owners, owners need to reach consensus amongst themselves.
 
-#### Language Owner
+##### Language Owner
 
-A language owner is the owner of the [`/docs/proposals/`](https://github.com/shader-slang/slang/tree/master/docs/proposals) directory. All new Slang language and core module features (e.g. new language syntax or new function or type in the Slang core module) starts with a design document submitted to this directory. The language and core module design must be approved by two language owners before any implementation pull request for the new language feature can be approved.
+A language owner is the owner of the [`/docs/proposals/`](https://github.com/shader-slang/slang/tree/master/docs/proposals) directory. All new Slang language and core module features (e.g. new language syntax, new functions, or new types in the Slang core module) starts with a design document submitted to this directory. The language and core module design must be approved by two language owners before any implementation pull request for the new language feature can be approved.
 
 ## Processes for Code Changes
 
 #### Process for Bug Fixes
-A bug fix starts with an GitHub issue describing the bug. Any community member can submit a pull request coming from your personal fork of Slang containing fixes for the bug. Such pull requests needs to be reviewed and approved by two committers who are owners of the files being changed by the pull request. Once the pull request is approved and passed all CI tests, it can be merged to the main branch. 
+A bug fix starts with a GitHub issue describing the bug. Any community member can submit a pull request coming from your personal fork of Slang containing fixes for the bug. Such pull requests needs to be reviewed and approved by two committers who are owners of the files being changed by the pull request. Once the pull request is approved and has passed all CI tests, it can be merged to the main branch.
+
+Pull requests are expected to be reviewed by the committers within 24 hours after they are created or updated, and to close within a week.
 
 #### Process for Slang Feature Changes
 
-Changes that add or modify syntax, language feature, Slang's core module, or the compilation and reflection API must go through our process for language changes. The full process is [documented here](/community/language-change-process).
+Changes that add or modify syntax, language features, Slang's core module, or the compilation and reflection API must go through our process for language changes. The full process is [documented here](/community/language-change-process).
 
 ## Submitting a Pull Request
 
 If you are ready to start contributing, please follow our [guide for creating a pull request](https://github.com/shader-slang/slang/blob/master/CONTRIBUTION.md). All pull requests are expected to meet our [bar of code quality](/community/code-quality).
 
 ## Become a Committer
 
-If you think you might be ready to be a committer, ask one of the reviewers of your pull request or another committer familiar with your work to see if they will nominate you. They will discuss that in #slang-committers discord — two others in that will need to second the nomination. See [how to become a committer here](/community/become-a-committer).
+If you think you might be ready to be a committer, ask one of the reviewers of your pull request or another committer familiar with your work to see if they will nominate you. They will discuss that in #slang-committers discord — two others in that will need to second the nomination. See [how to become a committer here](/community/become-a-committer).
+
+All committers are by-default the owner of all directories except the `docs/proposals` directory.
diff --git a/community/language-change-process.md b/community/language-change-process.md
@@ -2,26 +2,37 @@
 
 Changes that touch Slang's language and user-facing interfaces, including syntax, core module and public APIs need to follow the feature change process described in this document.
 
+Before undertaking the rest of the process, you are encouraged to “pitch” your idea on the Slang GitHub forum, in order to solicit informal feedback from the community. Feedback at this stage can help refine an idea, suggest directions, and identify potential collaborators.
+
 ## File a Feature Tracker
-The first step of doing a feature change is to file an "Feature Tracker" issue on our github with associated FeatureTracker label to begin including all template fields included. You will need to be a committer, or ask a committer or community member with greater access to the repo to do this, see [community structure](/community/index#community-structure) for how to do so.
+The first step of doing a feature change is to file a "Feature Tracker" issue on our github with associated FeatureTracker label to begin including all template fields included. You will need to be a committer, or ask a committer or community member with greater access to the repo to do this, see [community structure](/community/index#community-structure) for how to do so.
 
-This will be your "Feature tracker" and you'll need to keep it updated.
+This will be your "Feature Tracker" and you'll need to keep it updated.
 
 ## Feature Proposal
 In the feature tracker issue, include in the proposal a link to your design — a link to a PR, google doc, your choice.
 The proposal document should include the detailed design and proposed changes in the Slang compiler implementation.
 
-## Annouce the Experimental Feature
+## Announce the Experimental Feature
+
+Announce your intent to implement the feature in the [Announcement Channel in GitHub Discussions](https://github.com/shader-slang/slang/discussions/categories/announcements).
+
+## Iterate on design and implementation
+
+The OWNERs of docs/proposals (aka the “language OWNERs”) may weigh in on feature proposal issues to give guidance on what they expect will or will not be accepted as changes to the language.
+
+If it is clear to the language OWNERs that a proposed feature will not be accepted, they may close out the issue with an explanation of the reasoning.
+Ideally, you should wait to get positive feedback from at least one language OWNER before moving forward with implementation, to avoid the possibility of wasted effort.
 
-Announce the intent to experiment feature in the [Announcement Channel in GitHub Discussions](https://github.com/shader-slang/slang/discussions/categories/announcements). Assuming positive community support for your proposal, move your tracking issue’s status to “Implementation” and begin putting up PRs for reviews by relevant code OWNERs.
+Assuming positive community support for your proposal, move your tracking issue's status to "experimental" and begin putting up PRs for reviews by relevant code OWNERs.
 
-## Submit Pull Requests
+During the implementation period, you are expected to:
 
-Once announced, you can begin the work to implement the proposed feature, and iterate on implementation, design documentation and user reference documentation at the same time. The implementation can be merged to main branch at any frequency agreed by the dev team and the owner of the feature.
+- Keep reference docs (language ref, library ref) updated regularly along with implementation pull requests to allow the community to try your feature out.
 
-Reference docs (language ref, library ref) should be updated regularly during this process along with implementation pull requests to allow the community to try your feature out.
+- Commit the implementation of a new feature to top-of-tree, and marked the feature as experimental (and thus requiring an opt-in by users).
 
-Note that the implementation of a new feature is being made as commits to top-of-tree, albeit marked as experimental (and thus requiring an opt-in by users). The usual process for reviewing and merging pull requests will apply; there is not a separate, lower, quality bar for code changes related to experimental features.
+- Maintain the same level of code quality as other changes to the codebase. Note that the usual process for reviewing and merging pull requests will apply to your experimental feature implemnetation; there is not a separate, lower, quality bar for code changes related to experimental features.
 
 ## Transition to Stable Status
 
@@ -35,4 +46,4 @@ At decision time, the owners listed in `docs/proposals/OWNERS.txt` will discuss
 
 We expect that between 3-7 days will be given for community feedback in typical cases. Some lived experience is needed before we can make a policy about how long review periods need to last.
 
-The total time spent from creation of the tracking issue to when a feature is marked stable may vary with the complexity of a feature, but we expect that it will typically fall in the 1-3 month range. Even if a small feature might be proposed and implemented in a matter of days, it would need to be given sufficient time in the experimental state for community engagement and feedback before being considered for stabilization.
+The total time spent from creation of the tracking issue to when a feature is marked "stable" may vary with the complexity of a feature, but we expect that it will typically fall in the 1-3 month range. Even if a small feature might be proposed and implemented in a matter of days, it would need to be given sufficient time in the experimental state for community engagement and feedback before being considered for stabilization.
