From bd3a23dda3b696a93d9ac549c2d62f44cf408933 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Sat, 3 Mar 2018 20:32:01 +0800 Subject: [PATCH 1/2] doc: improve onboarding instructions - Suggest to use a TOTP app if the new collaborator cannot receive SMS messages from GitHub - Suggest to install node-core-utils and set up credentials before the onboarding session. - Ask about subsystem teams that they want to join - Note about squashing commits - Other small fixes --- COLLABORATOR_GUIDE.md | 6 +++--- doc/onboarding.md | 29 +++++++++++++++++++++++------ 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index e48e016bf7f0c8..b4e9a15aa50101 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -471,9 +471,9 @@ $ git node land $PRID ``` If it's the first time you ever use `node-core-utils`, you will be prompted -to type the password of your GitHub account in the console so the tool can -create the GitHub access token for you. If you do not want to do that, follow -[the guide of `node-core-utils`][node-core-utils-credentials] +to type the password of your GitHub account and the 2FA code in the console +so the tool can create the GitHub access token for you. If you do not want to +do that, follow [the guide of `node-core-utils`][node-core-utils-credentials] to set up your credentials manually. ### Technical HOWTO diff --git a/doc/onboarding.md b/doc/onboarding.md index a85e493d3c7561..2af91e168c8f83 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -6,16 +6,21 @@ onboarding session. ## One week before the onboarding session * If the new Collaborator is not yet a member of the nodejs GitHub organization, - confirm that they are using two-factor authentication. It will not be possible - to add them to the organization if they are not using two-factor - authentication. + confirm that they are using [two-factor authentication][]. It will not be + possible to add them to the organization if they are not using two-factor + authentication. If they cannot receive SMS messages from GitHub, try + [using a TOTP mobile app][]. * Announce the accepted nomination in a TSC meeting and in the TSC mailing list. +* Suggest the new Collaborator to install [`node-core-utils`][] and + [set up the credentials][] for it. ## 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). +* Ask them if they want to join any subsystem team. See + [Who to CC for Issues][who-to-cc]. ## Onboarding session @@ -87,7 +92,7 @@ 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) +* [**See "Who to CC in issues"**][who-to-cc] * This will come more naturally over time * For many of the teams listed there, you can ask to be added if you are interested @@ -183,7 +188,13 @@ onboarding session. ## Landing PRs -* See the Collaborator Guide: [Landing Pull Requests][] +See the Collaborator Guide: [Landing Pull Requests][]. + +Note that commits in one PR that belong to one logical change should +be squashed. It is rarely the case in onboarding exercises, so this +needs to be pointed out separately during the onboarding. + + ## Exercise: Make a PR adding yourself to the README @@ -202,9 +213,11 @@ onboarding session. for 48/72 hours to land). * Be sure to add the `PR-URL: ` and appropriate `Reviewed-By:` metadata. - * [`core-validate-commit`][] automates the validation of commit messages. * [`node-core-utils`][] automates the generation of metadata and the landing process. See the documentation of [`git-node`][]. + * [`core-validate-commit`][] automates the validation of commit messages. + This will be run during `git node land --final` of the [`git-node`][] + command. ## Final notes @@ -232,4 +245,8 @@ onboarding session. [Landing Pull Requests]: https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#landing-pull-requests [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0]: https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0 [Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ +[set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials +[two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ [Updating Node.js from Upstream]: ./onboarding-extras.md#updating-nodejs-from-upstream +[using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/ +[who-to-cc]: ./onboarding-extras.md#who-to-cc-in-issues From c24d0bb3f075545363c26a0e011cbf54edb9da38 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Wed, 7 Mar 2018 07:31:44 +0800 Subject: [PATCH 2/2] fix nits --- COLLABORATOR_GUIDE.md | 9 +++++---- doc/onboarding.md | 6 +++--- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index b4e9a15aa50101..ed1c5e9de7e0ac 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -470,10 +470,11 @@ $ npm install -g node-core-utils $ git node land $PRID ``` -If it's the first time you ever use `node-core-utils`, you will be prompted -to type the password of your GitHub account and the 2FA code in the console -so the tool can create the GitHub access token for you. If you do not want to -do that, follow [the guide of `node-core-utils`][node-core-utils-credentials] +If it's the first time you have used `node-core-utils`, you will be prompted +to type the password of your GitHub account and the two-factor authentication +code in the console so the tool can create the GitHub access token for you. +If you do not want to do that, follow +[the `node-core-utils` guide][node-core-utils-credentials] to set up your credentials manually. ### Technical HOWTO diff --git a/doc/onboarding.md b/doc/onboarding.md index 2af91e168c8f83..17d5e74f41ade9 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -12,14 +12,14 @@ onboarding session. [using a TOTP mobile app][]. * Announce the accepted nomination in a TSC meeting and in the TSC mailing list. -* Suggest the new Collaborator to install [`node-core-utils`][] and +* Suggest the new Collaborator install [`node-core-utils`][] and [set up the credentials][] for it. ## 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). -* Ask them if they want to join any subsystem team. See +* Ask them if they want to join any subsystem teams. See [Who to CC for Issues][who-to-cc]. ## Onboarding session @@ -240,7 +240,7 @@ needs to be pointed out separately during the onboarding. [Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md [`core-validate-commit`]: https://github.com/evanlucas/core-validate-commit -[`git-node`]: https://github.com/nodejs/node-core-utils#git-node +[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md [`node-core-utils`]: https://github.com/nodejs/node-core-utils [Landing Pull Requests]: https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#landing-pull-requests [https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0]: https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0