From 4dacb4c935a93dcad04e0971b3e1c8ef21914326 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Fri, 2 Jun 2017 21:35:45 +0200 Subject: [PATCH 1/9] doc: small makeover for onboarding.md --- doc/onboarding.md | 93 +++++++++++++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 40 deletions(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index e6bef3f631a2ac..56b522460c1d00 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -13,7 +13,9 @@ 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), + and to [the Members team](https://github.com/orgs/nodejs/teams/members) if + they are not already part of it. Note that this is the step that gives the account elevated privileges, so do not perform this step (or any subsequent steps) unless two-factor authentication is enabled on the new Collaborator's GitHub account. @@ -21,8 +23,7 @@ onboarding session. ## Onboarding session -* **thank you** for doing this -* will cover: +* This session will cover: * [local setup](#local-setup) * [project goals & values](#project-goals--values) * [managing the issue tracker](#managing-the-issue-tracker) @@ -32,33 +33,38 @@ onboarding session. ## Local setup * git: - * make sure you have whitespace=fix: `git config --global --add apply.whitespace fix` - * usually PR from your own github fork + * Make sure you have whitespace=fix: `git config --global --add apply.whitespace fix` + * Always continue to PR from your own github fork + * Branches in the nodejs/node repository are only for release lines * [See "Updating Node.js from Upstream"](./onboarding-extras.md#updating-nodejs-from-upstream) - * make new branches for all commits you make! + * Make new branches for all commits you make! - * notifications: - * use [https://github.com/notifications](https://github.com/notifications) or set up email - * watching the main repo will flood your inbox, so be prepared + * Notifications: + * Use [https://github.com/notifications](https://github.com/notifications) or set up email + * Watching the main repo will flood your inbox (several hundred notifications on typical weekdays), so be prepared * `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the best place to interact with the CTC / other collaborators + * If there are any questions after the session, this is a good place to ask! + * Presence is not mandatory, but please drop a note there if force-pushing to `master` ## Project goals & values - * collaborators are effectively part owners - * the project has the goals of its contributors + * Collaborators are effectively the collective owners of the project + * The project has the goals of its contributors - * but, there are some higher-level goals and values - * not everything belongs in core (if it can be done reasonably in userland, let it stay in userland) - * empathy towards users matters (this is in part why we onboard people) - * generally: try to be nice to people + * There are some higher-level goals and values + * Not everything belongs in core (if it can be done reasonably in userland, let it stay in userland) + * Empathy towards users matters (this is in part why we onboard people) + * Generally: try to be nice to people! + * The best outcome is for people who come to our issue tracker to feel like they can come back again. + + * We have a [Code of Conduct][] that you are expected to follow *and* hold others accountable to ## Managing the issue tracker - * you have (mostly) free rein – don't hesitate to close an issue if you are confident that it should be closed - * **IMPORTANT**: be nice about closing issues, let people know why, and that issues and PRs can be reopened if necessary - * Still need to follow the Code of Conduct + * You have (mostly) free rein – don't hesitate to close an issue if you are confident that it should be closed + * Be nice about closing issues! Let people know why, and that issues and PRs can be reopened if necessary * [**See "Labels"**](./onboarding-extras.md#labels) * There is [a bot](https://github.com/nodejs-github-bot/github-bot) that applies subsystem labels (for example, `doc`, `test`, `assert`, or `buffer`) so that we know what parts of the code base the pull request modifies. It is not perfect, of course. Feel free to apply relevant labels and remove irrelevant labels from pull requests and issues. @@ -69,7 +75,8 @@ onboarding session. * When adding a semver label, add a comment explaining why you're adding it. Do it right away so you don't forget! * [**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) - * will also come more naturally over time + * For many of the teams listed there, you can just ask to be added if you are interested + * This will come more naturally over time * 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 contents should not be shared externally. @@ -100,18 +107,20 @@ onboarding session. (especially if it just has nits left). * Approving a change * Collaborators indicate that they have reviewed and approve of the - the changes in a pull request by commenting with `LGTM`, which stands - for "looks good to me". - * You have the power to `LGTM` another collaborator's (including TSC/CTC - members) work. - * You may not `LGTM` your own pull requests. - * You have the power to `LGTM` anyone else's pull requests. + the changes in a pull request using Github’s approval interface + * Some people like to comment `LGTM` (“Looks Good To Me”) + * You have the power to approve any other collaborator's work. + * You may not approve your own pull requests. + * When explicitly using `Changes requested`, show empathy – comments will + usually be addressed even if you don’t use it. + * If you do, it is nice if you are available later to check whether your + comments have been addressed * What belongs in node: - * opinions vary, but I find the following helpful: - * if node itself needs it (due to historic reasons), then it belongs in node - * that is to say, url is there because of http, freelist is there because of http, et al - * also, things that cannot be done outside of core, or only with significant pain (example: async-wrap) + * Opinions vary – it’s good to have a broad collaborator base for that reason! + * If node itself needs it (due to historic reasons), then it belongs in node + * That is to say, url is there because of http, freelist is there because of http, et al + * Also, things that cannot be done outside of core, or only with significant pain (for example `async_hooks`) * Continuous Integration (CI) Testing: * [https://ci.nodejs.org/](https://ci.nodejs.org/) @@ -136,26 +145,30 @@ onboarding session. ## Exercise: Make a PR adding yourself to the README - * Example: [https://github.com/nodejs/node/commit/7b09aade8468e1c930f36b9c81e6ac2ed5bc8732](https://github.com/nodejs/node/commit/7b09aade8468e1c930f36b9c81e6ac2ed5bc8732) - * For raw commit message: `git log 7b09aade8468e1c930f36b9c81e6ac2ed5bc8732 -1` + * Example: [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0](https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0) + * For raw commit message: `git log ce986de829457c39257cd205067602e765768fb0 -1` * Collaborators are in alphabetical order by GitHub username. * Optionally, include your personal pronouns. * Label your pull request with the `doc` subsystem label. * Run CI on your PR. - * After a `LGTM` or two, land the PR. + * After one or two approvals, land the PR. * Be sure to add the `PR-URL: ` and appropriate `Reviewed-By:` metadata! + * [`core-validate-commit`][] helps a lot with this – install and use it if you can! + * If you use Chrome, [`node-review`][] fetches the metadata for you ## Final notes - * don't worry about making mistakes: everybody makes them, there's a lot to internalize and that takes time (and we recognize that!) - * very few (no?) mistakes are unrecoverable - * the existing collaborators trust you and are grateful for your help! - * other repos: - * [https://github.com/nodejs/dev-policy](https://github.com/nodejs/dev-policy) - * [https://github.com/nodejs/NG](https://github.com/nodejs/NG) - * [https://github.com/nodejs/api](https://github.com/nodejs/api) + * Don't worry about making mistakes: everybody makes them, there's a lot to internalize and that takes time (and we recognize that!) + * No mistakes are unrecoverable! + * The existing collaborators trust you and are grateful for your help! + * Other repositories: + * [https://github.com/nodejs/CTC](https://github.com/nodejs/CTC) * [https://github.com/nodejs/build](https://github.com/nodejs/build) - * [https://github.com/nodejs/docs](https://github.com/nodejs/docs) * [https://github.com/nodejs/nodejs.org](https://github.com/nodejs/nodejs.org) * [https://github.com/nodejs/readable-stream](https://github.com/nodejs/readable-stream) * [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS) + * [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm) + +[Code of Conduct]: https://github.com/nodejs/TSC/blob/master/CODE_OF_CONDUCT.md +[`core-validate-commit`]: https://github.com/evanlucas/core-validate-commit +[`node-review`]: https://github.com/evanlucas/node-review From c5da1ca0d03aa9ef89c44af067b31079f568ce3d Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Fri, 2 Jun 2017 22:47:20 +0200 Subject: [PATCH 2/9] =?UTF-8?q?[squash]=20update=20based=20on=20refack?= =?UTF-8?q?=E2=80=99s=20review?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/onboarding.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index 56b522460c1d00..8ebf8bc9b009b2 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -44,7 +44,7 @@ onboarding session. * Watching the main repo will flood your inbox (several hundred notifications on typical weekdays), so be prepared * `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the best place to interact with the CTC / other collaborators - * If there are any questions after the session, this is a good place to ask! + * If there are any questions after the session, a good place to ask is there! * Presence is not mandatory, but please drop a note there if force-pushing to `master` @@ -109,18 +109,20 @@ onboarding session. * Collaborators indicate that they have reviewed and approve of the the changes in a pull request using Github’s approval interface * Some people like to comment `LGTM` (“Looks Good To Me”) - * You have the power to approve any other collaborator's work. - * You may not approve your own pull requests. + * You have the authority to approve any other collaborator’s work. + * You cannot approve your own pull requests. * When explicitly using `Changes requested`, show empathy – comments will usually be addressed even if you don’t use it. * If you do, it is nice if you are available later to check whether your comments have been addressed + * Other collaborators will usually take `Changes requested` to mean that + you are considering some of your comments to block the PR from landing. * What belongs in node: * Opinions vary – it’s good to have a broad collaborator base for that reason! * If node itself needs it (due to historic reasons), then it belongs in node - * That is to say, url is there because of http, freelist is there because of http, et al - * Also, things that cannot be done outside of core, or only with significant pain (for example `async_hooks`) + * That is to say, url is there because of http, freelist is there because of http, etc. + * Things that cannot be done outside of core, or only with significant pain (for example `async_hooks`) * Continuous Integration (CI) Testing: * [https://ci.nodejs.org/](https://ci.nodejs.org/) @@ -159,7 +161,7 @@ onboarding session. ## Final notes * Don't worry about making mistakes: everybody makes them, there's a lot to internalize and that takes time (and we recognize that!) - * No mistakes are unrecoverable! + * Almost any mistake you could make can be fixed or reverted. * The existing collaborators trust you and are grateful for your help! * Other repositories: * [https://github.com/nodejs/CTC](https://github.com/nodejs/CTC) From 3a99236783786c8d41035c1f8bc0548351843a60 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Sat, 3 Jun 2017 01:07:36 +0200 Subject: [PATCH 3/9] [squash] make things less effectively --- doc/onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index 8ebf8bc9b009b2..a86219d797041e 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -50,7 +50,7 @@ onboarding session. ## Project goals & values - * Collaborators are effectively the collective owners of the project + * Collaborators are the collective owners of the project * The project has the goals of its contributors * There are some higher-level goals and values From 20ee1088851d5d808c6920e949a1759b4a9c109c Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Sat, 3 Jun 2017 01:11:35 +0200 Subject: [PATCH 4/9] =?UTF-8?q?[squash]=20=E2=80=93=20=E2=86=92=20;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index a86219d797041e..150cc9390669c0 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -63,7 +63,7 @@ onboarding session. ## Managing the issue tracker - * You have (mostly) free rein – don't hesitate to close an issue if you are confident that it should be closed + * You have (mostly) free rein; don't hesitate to close an issue if you are confident that it should be closed * Be nice about closing issues! Let people know why, and that issues and PRs can be reopened if necessary * [**See "Labels"**](./onboarding-extras.md#labels) From e7716023324fac72a1df89938e8c30496b818f30 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Sat, 3 Jun 2017 01:13:29 +0200 Subject: [PATCH 5/9] =?UTF-8?q?[squash]=20address=20more=20of=20Trott?= =?UTF-8?q?=E2=80=99s=20nits?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/onboarding.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index 150cc9390669c0..7bc24d523dbd7c 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -75,8 +75,9 @@ onboarding session. * When adding a semver label, add a comment explaining why you're adding it. Do it right away so you don't forget! * [**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) - * For many of the teams listed there, you can just ask to be added if you are interested * This will come more naturally over time + * For many of the teams listed there, you can ask to be added if you are interested + * 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 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 contents should not be shared externally. @@ -118,9 +119,9 @@ onboarding session. * Other collaborators will usually take `Changes requested` to mean that you are considering some of your comments to block the PR from landing. - * What belongs in node: + * What belongs in Node.js: * Opinions vary – it’s good to have a broad collaborator base for that reason! - * If node itself needs it (due to historic reasons), then it belongs in node + * If Node.js itself needs it (due to historic reasons), then it belongs in Node.js * That is to say, url is there because of http, freelist is there because of http, etc. * Things that cannot be done outside of core, or only with significant pain (for example `async_hooks`) From 3f1037916c60e23bf2a026164f9493910cb40532 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Sat, 3 Jun 2017 01:15:21 +0200 Subject: [PATCH 6/9] =?UTF-8?q?[squash]=20collaborators=20=E2=86=92=20Coll?= =?UTF-8?q?aborators?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/onboarding.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index 7bc24d523dbd7c..dbe176d8b34a34 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -43,7 +43,7 @@ onboarding session. * Use [https://github.com/notifications](https://github.com/notifications) or set up email * Watching the main repo will flood your inbox (several hundred notifications on typical weekdays), so be prepared - * `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the best place to interact with the CTC / other collaborators + * `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the best place to interact with the CTC / other Collaborators * If there are any questions after the session, a good place to ask is there! * Presence is not mandatory, but please drop a note there if force-pushing to `master` @@ -79,7 +79,7 @@ onboarding session. * For many of the teams listed there, you can ask to be added if you are interested * 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 an eye on it by opening an issue at the private [nodejs/moderation](https://github.com/nodejs/moderation) repository. + * 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 contents should not be shared externally. * You can find the full moderation policy [here](https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md). @@ -116,7 +116,7 @@ onboarding session. usually be addressed even if you don’t use it. * If you do, it is nice if you are available later to check whether your comments have been addressed - * Other collaborators will usually take `Changes requested` to mean that + * Other Collaborators will usually take `Changes requested` to mean that you are considering some of your comments to block the PR from landing. * What belongs in Node.js: @@ -163,7 +163,7 @@ onboarding session. * 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/CTC](https://github.com/nodejs/CTC) * [https://github.com/nodejs/build](https://github.com/nodejs/build) From 8786e753044d1e8a31ec9e6a9026dcb46bc9b856 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Wed, 7 Jun 2017 21:28:40 +0200 Subject: [PATCH 7/9] =?UTF-8?q?[squash]=20new=20branches:=20commit=20?= =?UTF-8?q?=E2=86=92=20PR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/onboarding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index dbe176d8b34a34..3159cd5bee2de4 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -37,7 +37,7 @@ onboarding session. * Always continue to PR from your own github fork * Branches in the nodejs/node repository are only for release lines * [See "Updating Node.js from Upstream"](./onboarding-extras.md#updating-nodejs-from-upstream) - * Make new branches for all commits you make! + * Make a new branch for each PR you submit. * Notifications: * Use [https://github.com/notifications](https://github.com/notifications) or set up email From 16787de6b0415bd7adc445aece64847fa4b55739 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Wed, 7 Jun 2017 21:30:47 +0200 Subject: [PATCH 8/9] =?UTF-8?q?[squash]=20drop=20dup=E2=80=99ed=20sentence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/onboarding.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index 3159cd5bee2de4..e18132105d084b 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -54,7 +54,6 @@ onboarding session. * The project has the goals of its contributors * There are some higher-level goals and values - * Not everything belongs in core (if it can be done reasonably in userland, let it stay in userland) * Empathy towards users matters (this is in part why we onboard people) * Generally: try to be nice to people! * The best outcome is for people who come to our issue tracker to feel like they can come back again. From b9a776f139d9361c7a33f9971d927df945c49bcc Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Wed, 7 Jun 2017 21:34:27 +0200 Subject: [PATCH 9/9] [squash] requested changes mentions --- doc/onboarding.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/onboarding.md b/doc/onboarding.md index e18132105d084b..e1e10d88b30243 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -115,8 +115,10 @@ onboarding session. usually be addressed even if you don’t use it. * If you do, it is nice if you are available later to check whether your comments have been addressed - * Other Collaborators will usually take `Changes requested` to mean that - you are considering some of your comments to block the PR from landing. + * If you see that the requested changes have been made, you can clear another collaborator's + `Changes requested` review. + * Use `Changes requested` to indicate that you are considering some of + your comments to block the PR from landing. * What belongs in Node.js: * Opinions vary – it’s good to have a broad collaborator base for that reason!