From c3cfefc2d3158471a64a1d3b6a121cfbb0a6b52d Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 13 Jul 2021 15:15:59 -0700 Subject: [PATCH] doc: standardize on not capitalizing _collaborator_ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sometimes we capitalize _collaborator_ and sometimes not. After consulting the Microsoft Style Guide and The Chicago Manual of Style, I've concluded it is best to not capitalize it. For consistency, apply that to our various .md files. Refs: https://docs.microsoft.com/en-us/style-guide/capitalization PR-URL: https://github.com/nodejs/node/pull/39379 Reviewed-By: Antoine du Hamel Reviewed-By: Gireesh Punathil Reviewed-By: Colin Ihrig Reviewed-By: Michaël Zasso Reviewed-By: Zijian Liu Reviewed-By: Tobias Nießen Reviewed-By: James M Snell --- GOVERNANCE.md | 50 ++++++++++++------------ doc/guides/collaborator-guide.md | 40 +++++++++---------- doc/guides/commit-queue.md | 6 +-- doc/guides/contributing/pull-requests.md | 20 +++++----- doc/guides/offboarding.md | 16 ++++---- onboarding.md | 12 +++--- 6 files changed, 72 insertions(+), 72 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index b4d00c761f0d7a..81635352ac5f6a 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -28,32 +28,32 @@ See: ## Collaborators -Node.js Core Collaborators maintain the [nodejs/node][] GitHub repository. -The GitHub team for Node.js Core Collaborators is @nodejs/collaborators. +Node.js core collaborators maintain the [nodejs/node][] GitHub repository. +The GitHub team for Node.js core collaborators is @nodejs/collaborators. Collaborators have: * Commit access to the [nodejs/node][] repository * Access to the Node.js continuous integration (CI) jobs -Both Collaborators and non-Collaborators may propose changes to the Node.js +Both collaborators and non-collaborators may propose changes to the Node.js source code. The mechanism to propose such a change is a GitHub pull request. Collaborators review and merge (_land_) pull requests. -Two Collaborators must approve a pull request before the pull request can land. -(One Collaborator approval is enough if the pull request has been open for more -than 7 days.) Approving a pull request indicates that the Collaborator accepts -responsibility for the change. Approval must be from Collaborators who are not +Two collaborators must approve a pull request before the pull request can land. +(One collaborator approval is enough if the pull request has been open for more +than 7 days.) Approving a pull request indicates that the collaborator accepts +responsibility for the change. Approval must be from collaborators who are not authors of the change. -If a Collaborator opposes a proposed change, then the change cannot land. The +If a collaborator opposes a proposed change, then the change cannot land. The exception is if the TSC votes to approve the change despite the opposition. Usually, involving the TSC is unnecessary. Often, discussions or further changes -result in Collaborators removing their opposition. +result in collaborators removing their opposition. See: -* [List of Collaborators](./README.md#current-project-team-members) -* [A guide for Collaborators](./doc/guides/collaborator-guide.md) +* [List of collaborators](./README.md#current-project-team-members) +* [A guide for collaborators](./doc/guides/collaborator-guide.md) ### Collaborator activities @@ -63,12 +63,12 @@ See: * Participation in working groups * Merging pull requests -The TSC can remove inactive Collaborators or provide them with _Emeritus_ +The TSC can remove inactive collaborators or provide them with _Emeritus_ status. Emeriti may request that the TSC restore them to active status. ## Technical Steering Committee -A subset of the Collaborators forms the Technical Steering Committee (TSC). +A subset of the collaborators forms the Technical Steering Committee (TSC). The TSC has final authority over this project, including: * Technical direction @@ -76,7 +76,7 @@ The TSC has final authority over this project, including: * Contribution policy * GitHub repository hosting * Conduct guidelines -* Maintaining the list of Collaborators +* Maintaining the list of collaborators The current list of TSC members is in [the project README](./README.md#current-project-team-members). @@ -95,7 +95,7 @@ agenda is not to review or approve all patches. Collaborators review and approve patches on GitHub. Any community member can create a GitHub issue asking that the TSC review -something. If consensus-seeking fails for an issue, a Collaborator may apply the +something. If consensus-seeking fails for an issue, a collaborator may apply the `tsc-agenda` label. That will add it to the TSC meeting agenda. Before each TSC meeting, the meeting chair will share the agenda with members of @@ -120,11 +120,11 @@ the issue tracker is: ## Collaborator nominations -Existing Collaborators can nominate someone to become a Collaborator. Nominees +Existing collaborators can nominate someone to become a collaborator. Nominees should have significant and valuable contributions across the Node.js organization. -To nominate a new Collaborator, open an issue in the [nodejs/node][] repository. +To nominate a new collaborator, open an issue in the [nodejs/node][] repository. Provide a summary of the nominee's contributions. For example: * Commits in the [nodejs/node][] repository. @@ -144,25 +144,25 @@ Provide a summary of the nominee's contributions. For example: organization * Other participation in the wider Node.js community -Mention @nodejs/collaborators in the issue to notify other Collaborators about +Mention @nodejs/collaborators in the issue to notify other collaborators about the nomination. -The nomination passes if no Collaborators oppose it after one week. Otherwise, +The nomination passes if no collaborators oppose it after one week. Otherwise, the nomination fails. There are steps a nominator can take in advance to make a nomination as -frictionless as possible. To request feedback from other Collaborators in - private, use the [Collaborators discussion page][] - (which only Collaborators may view). A nominator may also work with the +frictionless as possible. To request feedback from other collaborators in + private, use the [collaborators discussion page][] + (which only collaborators may view). A nominator may also work with the nominee to improve their contribution profile. Collaborators might overlook someone with valuable contributions. In that case, -the contributor may open an issue or contact a Collaborator to request a +the contributor may open an issue or contact a collaborator to request a nomination. ### Onboarding -After the nomination passes, a TSC member onboards the new Collaborator. See +After the nomination passes, a TSC member onboards the new collaborator. See [the onboarding guide](./onboarding.md) for details of the onboarding process. @@ -171,7 +171,7 @@ process. The TSC follows a [Consensus Seeking][] decision-making model per the [TSC Charter][]. -[Collaborators discussion page]: https://github.com/orgs/nodejs/teams/collaborators/discussions [Consensus Seeking]: https://en.wikipedia.org/wiki/Consensus-seeking_decision-making [TSC Charter]: https://github.com/nodejs/TSC/blob/HEAD/TSC-Charter.md +[collaborators discussion page]: https://github.com/orgs/nodejs/teams/collaborators/discussions [nodejs/node]: https://github.com/nodejs/node diff --git a/doc/guides/collaborator-guide.md b/doc/guides/collaborator-guide.md index cdc6c6da1dbad3..409523025819bc 100644 --- a/doc/guides/collaborator-guide.md +++ b/doc/guides/collaborator-guide.md @@ -1,4 +1,4 @@ -# Node.js Collaborator Guide +# Node.js collaborator guide ## Contents @@ -36,14 +36,14 @@ * [How can I help?](#how-can-i-help) * [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker) -This document explains how Collaborators manage the Node.js project. +This document explains how collaborators manage the Node.js project. Collaborators should understand the [guidelines for new contributors](../../CONTRIBUTING.md) and the [project governance model](../../GOVERNANCE.md). ## Issues and pull requests -Mind these guidelines, the opinions of other Collaborators, and guidance of the +Mind these guidelines, the opinions of other collaborators, and guidance of the [TSC][]. Notify other qualified parties for more input on an issue or a pull request. See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker). @@ -71,7 +71,7 @@ issues and pull requests can always be re-opened if necessary. A pull request is _author ready_ when: * There is a CI run in progress or completed. -* There is at least one Collaborator approval. +* There is at least one collaborator approval. * There are no outstanding review comments. Please always add the `author ready` label to the pull request in that case. @@ -83,7 +83,7 @@ When you open a pull request, [start a CI](#testing-and-ci) right away. Later, after new code changes or rebasing, start a new CI. As soon as the pull request is ready to land, please do so. This allows other -Collaborators to focus on other pull requests. If your pull request is not ready +collaborators to focus on other pull requests. If your pull request is not ready to land but is [author ready](#author-ready-pull-requests), add the `author ready` label. If you wish to land the pull request yourself, use the "assign yourself" link to self-assign it. @@ -113,25 +113,25 @@ issues. If a user opens a security issue in the public repository: ## Accepting modifications Contributors propose modifications to Node.js using GitHub pull requests. This -includes modifications proposed by TSC members and other Collaborators. A pull +includes modifications proposed by TSC members and other collaborators. A pull request must pass code review and CI before landing into the codebase. ### Code reviews -At least two Collaborators must approve a pull request before the pull request -lands. One Collaborator approval is enough if the pull request has been open +At least two collaborators must approve a pull request before the pull request +lands. One collaborator approval is enough if the pull request has been open for more than seven days. -Approving a pull request indicates that the Collaborator accepts responsibility +Approving a pull request indicates that the collaborator accepts responsibility for the change. -Approval must be from Collaborators who are not authors of the change. +Approval must be from collaborators who are not authors of the change. In some cases, it might be necessary to summon a GitHub team to a pull request for review by @-mention. See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker). -If you are the first Collaborator to approve a pull request that has no CI yet, +If you are the first collaborator to approve a pull request that has no CI yet, please [start one](#testing-and-ci). Please also start a new CI if the pull request creator pushed new code since the last CI run. @@ -173,7 +173,7 @@ adding the `tsc-agenda` label to the issue. ### Waiting for approvals -Before landing pull requests, allow 48 hours for input from other Collaborators. +Before landing pull requests, allow 48 hours for input from other collaborators. Certain types of pull requests can be fast-tracked and can land after a shorter delay. For example: @@ -185,14 +185,14 @@ delay. For example: * Regressions that happen right before a release, or reported soon after. To propose fast-tracking a pull request, apply the `fast-track` label. Then add -a comment that Collaborators can upvote. +a comment that collaborators can upvote. If someone disagrees with the fast-tracking request, remove the label. Do not fast-track the pull request in that case. -The pull request can be fast-tracked if two Collaborators approve the +The pull request can be fast-tracked if two collaborators approve the fast-tracking request. To land, the pull request itself still needs two -Collaborator approvals and a passing CI. +collaborator approvals and a passing CI. Collaborators can request fast-tracking of pull requests they did not author. In that case only, the request itself is also one fast-track approval. Upvote @@ -372,7 +372,7 @@ providing a Public API in such cases. #### Unintended breaking changes Sometimes, a change intended to be non-breaking turns out to be a breaking -change. If such a change lands on the master branch, a Collaborator can revert +change. If such a change lands on the master branch, a collaborator can revert it. As an alternative to reverting, the TSC can apply the semver-major label after-the-fact. @@ -474,7 +474,7 @@ Do this if a pull request or issue: * Is labeled `semver-major`, or * Has a significant impact on the codebase, or * Is controversial, or -* Is at an impasse among Collaborators who are participating in the discussion. +* Is at an impasse among collaborators who are participating in the discussion. @-mention the `@nodejs/tsc` GitHub team if you want to elevate an issue to the [TSC][]. Do not use the GitHub UI on the right-hand side to assign to @@ -659,7 +659,7 @@ for that commit. This is an opportunity to fix commit messages. issue. A commit message can include more than one `Fixes:` lines. * Optional: One or more `Refs:` lines referencing a URL for any relevant background. - * Required: A `Reviewed-By: Name ` line for each Collaborator who + * Required: A `Reviewed-By: Name ` line for each collaborator who reviewed the change. * Useful for @mentions / contact list if something goes wrong in the pull request. @@ -775,7 +775,7 @@ There are several LTS-related labels: release. For example, `land-on-v10.x` would be for a change to land in Node.js 10.x. -Any Collaborator can attach these labels to any pull request/issue. As commits +Any collaborator can attach these labels to any pull request/issue. As commits land on the staging branches, the backporter removes the `lts-watch-` label. Likewise, as commits land in an LTS release, the releaser removes the `land-on-` label. @@ -847,7 +847,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s ` can help. * `author-ready` - A pull request is _author ready_ when: * There is a CI run in progress or completed. - * There is at least one Collaborator approval (or two TSC approvals for + * There is at least one collaborator approval (or two TSC approvals for semver-major pull requests). * There are no outstanding review comments. diff --git a/doc/guides/commit-queue.md b/doc/guides/commit-queue.md index 8c3fca28ec605f..3ad40390e64847 100644 --- a/doc/guides/commit-queue.md +++ b/doc/guides/commit-queue.md @@ -5,7 +5,7 @@ *tl;dr: You can land Pull Requests by adding the `commit-queue` label to it.* Commit Queue is an experimental feature for the project which simplifies the -landing process by automating it via GitHub Actions. With it, Collaborators can +landing process by automating it via GitHub Actions. With it, collaborators can land Pull Requests by adding the `commit-queue` label to a PR. All checks will run via node-core-utils, and if the Pull Request is ready to land, the Action will rebase it and push to master. @@ -48,7 +48,7 @@ of the commit queue: commit that will be correctly handled by the [`--autosquash`](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash) option 2. A CI must've ran and succeeded since the last change on the PR -3. A Collaborator must have approved the PR since the last change +3. A collaborator must have approved the PR since the last change 4. Only Jenkins CI is checked (Actions, V8 CI and CITGM are ignored) ## Implementation @@ -108,7 +108,7 @@ until all PRs have done the steps above. ## Reverting broken commits -Reverting broken commits is done manually by Collaborators, just like when +Reverting broken commits is done manually by collaborators, just like when commits are landed manually via `git node land`. An easy way to revert is a good feature for the project, but is not explicitly required for the Commit Queue to work because the Action lands PRs just like collaborators do today. If diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md index 1820fae69fb4df..94c9bb69424cfd 100644 --- a/doc/guides/contributing/pull-requests.md +++ b/doc/guides/contributing/pull-requests.md @@ -41,7 +41,7 @@ Node.js. We cannot accept such patches. In case of doubt, open an issue in the [issue tracker](https://github.com/nodejs/node/issues/) or contact one of the -[project Collaborators](https://github.com/nodejs/node/#current-project-team-members). +[project collaborators](https://github.com/nodejs/node/#current-project-team-members). Node.js has many channels on the [OpenJS Foundation Slack](https://slack-invite.openjsf.org/). Interesting @@ -335,7 +335,7 @@ unhelpful is likely safe to ignore. ### Step 10: Landing In order to land, a Pull Request needs to be reviewed and [approved][] by -at least two Node.js Collaborators (one Collaborator approval is enough if the +at least two Node.js collaborators (one collaborator approval is enough if the pull request has been open for more than 7 days) and pass a [CI (Continuous Integration) test run][]. After that, as long as there are no objections from other contributors, the Pull Request can be merged. If you find @@ -391,7 +391,7 @@ change over time. The first impression you give to a new contributor never does. Nits (requests for small changes that are not essential) are fine, but try to avoid stalling the Pull Request. Most nits can typically be fixed by the -Node.js Collaborator landing the Pull Request but they can also be an +Node.js collaborator landing the Pull Request but they can also be an opportunity for the contributor to learn a bit more about the project. It is always good to clearly indicate nits when you comment: e.g. @@ -434,7 +434,7 @@ commit. ### Approving a change -Any Node.js core Collaborator (any GitHub user with commit rights in the +Any Node.js core collaborator (any GitHub user with commit rights in the `nodejs/node` repository) is authorized to approve any other contributor's work. Collaborators are not permitted to approve their own Pull Requests. @@ -503,9 +503,9 @@ feedback. All Pull Requests that contain changes to code must be run through continuous integration (CI) testing at [https://ci.nodejs.org/][]. -Only Node.js core Collaborators with commit rights to the `nodejs/node` +Only Node.js core collaborators with commit rights to the `nodejs/node` repository may start a CI testing run. The specific details of how to do -this are included in the new Collaborator [Onboarding guide][]. +this are included in the new collaborator [Onboarding guide][]. Ideally, the code change will pass ("be green") on all platform configurations supported by Node.js (there are over 30 platform configurations currently). @@ -551,9 +551,9 @@ Every Pull Request needs to be tested to make sure that it works on the platforms that Node.js supports. This is done by running the code through the CI system. -Only a Collaborator can start a CI run. Usually one of them will do it +Only a collaborator can start a CI run. Usually one of them will do it for you as approvals for the Pull Request come in. -If not, you can ask a Collaborator to start a CI run. +If not, you can ask a collaborator to start a CI run. ### Waiting until the pull request gets landed @@ -567,7 +567,7 @@ widely used, so don't be discouraged! ### Check out the collaborator guide If you want to know more about the code review and the landing process, see the -[Collaborator Guide][]. +[collaborator guide][]. ### Appendix: subsystems @@ -583,10 +583,10 @@ More than one subsystem may be valid for any particular issue or pull request. [Building guide]: ../../../BUILDING.md [CI (Continuous Integration) test run]: #ci-testing [Code of Conduct]: https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md -[Collaborator Guide]: ../collaborator-guide.md [Onboarding guide]: ../../../onboarding.md [approved]: #getting-approvals-for-your-pull-request [benchmark results]: ../writing-and-running-benchmarks.md +[collaborator guide]: ../collaborator-guide.md [guide for writing tests in Node.js]: ../writing-tests.md [hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment [https://ci.nodejs.org/]: https://ci.nodejs.org/ diff --git a/doc/guides/offboarding.md b/doc/guides/offboarding.md index 0d73e412089b7f..2c5ecfa9018f6c 100644 --- a/doc/guides/offboarding.md +++ b/doc/guides/offboarding.md @@ -1,14 +1,14 @@ # Offboarding -This document is a checklist of things to do when a Collaborator becomes -Emeritus or leaves the project. +This document is a checklist of things to do when a collaborator becomes +emeritus or leaves the project. -* Remove the Collaborator from the @nodejs/collaborators team. -* Open a fast-track pull request to move the Collaborator to Collaborator - Emeriti in README.md. -* Determine what GitHub teams the Collaborator belongs to. In consultation with - the Collaborator, determine which of those teams they should be removed from. - * Some teams may also require a pull request to remove the Collaborator from +* Remove the collaborator from the @nodejs/collaborators team. +* Open a fast-track pull request to move the collaborator to the collaborator + emeriti list in README.md. +* Determine what GitHub teams the collaborator belongs to. In consultation with + the collaborator, determine which of those teams they should be removed from. + * Some teams may also require a pull request to remove the collaborator from a team listing. For example, if someone is removed from @nodejs/build, they should also be removed from the Build WG README.md file in the repository. diff --git a/onboarding.md b/onboarding.md index 938d683ee50e4a..1cab6132e308c2 100644 --- a/onboarding.md +++ b/onboarding.md @@ -1,6 +1,6 @@ # Onboarding -This document is an outline of the things we tell new Collaborators at their +This document is an outline of the things we tell new collaborators at their onboarding session. ## One week before the onboarding session @@ -18,7 +18,7 @@ onboarding session. ## Fifteen minutes before the onboarding session * Prior to the onboarding session, add the new Collaborator to - [the Collaborators team](https://github.com/orgs/nodejs/teams/collaborators). + [the collaborators team](https://github.com/orgs/nodejs/teams/collaborators). * Ask them if they want to join any subsystem teams. See [Who to CC in the issue tracker][who-to-cc]. @@ -46,7 +46,7 @@ onboarding session. * `git merge --ff-only upstream/master` (or `REMOTENAME/BRANCH`) * Make a new branch for each PR you submit. * Membership: Consider making your membership in the Node.js GitHub - organization public. This makes it easier to identify Collaborators. + organization public. This makes it easier to identify collaborators. Instructions on how to do that are available at [Publicizing or hiding organization membership][]. @@ -101,11 +101,11 @@ The project has two venues for real-time discussion: * Some are WGs with some process around adding people, others are only there for notifications -* When a discussion gets heated, you can request that other Collaborators keep +* When a discussion gets heated, you can request that other collaborators keep an eye on it by opening an issue at the private [nodejs/moderation](https://github.com/nodejs/moderation) repository. * This is a repository to which all members of the `nodejs` GitHub - organization (not just Collaborators on Node.js core) have access. Its + organization (not just collaborators on Node.js core) have access. Its contents should not be shared externally. * You can find the full moderation policy [here](https://github.com/nodejs/admin/blob/HEAD/Moderation-Policy.md). @@ -224,7 +224,7 @@ needs to be pointed out separately during the onboarding. * Don't worry about making mistakes: everybody makes them, there's a lot to internalize and that takes time (and we recognize that!) * Almost any mistake you could make can be fixed or reverted. -* The existing Collaborators trust you and are grateful for your help! +* The existing collaborators trust you and are grateful for your help! * Other repositories: * [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC) * [https://github.com/nodejs/build](https://github.com/nodejs/build)