diff options
author | Rich Trott <rtrott@gmail.com> | 2021-07-14 01:15:59 +0300 |
---|---|---|
committer | Michaël Zasso <targos@protonmail.com> | 2021-09-04 16:14:28 +0300 |
commit | c3cfefc2d3158471a64a1d3b6a121cfbb0a6b52d (patch) | |
tree | 5e010b5a0b41f337daec10ed89c56544dbf5d144 /doc | |
parent | e9c46107d7ee775439b60655b9e7e137a60353fd (diff) |
doc: standardize on not capitalizing _collaborator_
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 <duhamelantoine1995@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/guides/collaborator-guide.md | 40 | ||||
-rw-r--r-- | doc/guides/commit-queue.md | 6 | ||||
-rw-r--r-- | doc/guides/contributing/pull-requests.md | 20 | ||||
-rw-r--r-- | doc/guides/offboarding.md | 16 |
4 files changed, 41 insertions, 41 deletions
diff --git a/doc/guides/collaborator-guide.md b/doc/guides/collaborator-guide.md index cdc6c6da1db..40952302581 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 <email>` line for each Collaborator who + * Required: A `Reviewed-By: Name <email>` 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 <file>` 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 8c3fca28ec6..3ad40390e64 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 1820fae69fb..94c9bb69424 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 0d73e412089..2c5ecfa9018 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 <https://github.com/nodejs/build> repository. |