Skip to content

Commit

Permalink
doc: improve onboarding instructions
Browse files Browse the repository at this point in the history
- 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

PR-URL: #19108
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
  • Loading branch information
joyeecheung authored and MylesBorins committed Mar 20, 2018
1 parent 9ec0eab commit 27088cf
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 11 deletions.
9 changes: 5 additions & 4 deletions COLLABORATOR_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -469,10 +469,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 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
Expand Down
31 changes: 24 additions & 7 deletions doc/onboarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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 teams. See
[Who to CC for Issues][who-to-cc].

## Onboarding session

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

<!-- TODO(joyeechueng): provide examples about "one logical change" -->

## Exercise: Make a PR adding yourself to the README

Expand All @@ -202,9 +213,11 @@ onboarding session.
for 48/72 hours to land).
* Be sure to add the `PR-URL: <full-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

Expand All @@ -227,9 +240,13 @@ onboarding session.

[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
[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

0 comments on commit 27088cf

Please sign in to comment.