Skip to content

doc: improve onboarding instructions #19108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

doc: improve onboarding instructions #19108

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd3a23d
doc: improve onboarding instructions
joyeecheung Mar 3, 2018
c24d0bb
fix nits
joyeecheung Mar 6, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,9 +471,9 @@ $ git node land $PRID
```

If it's the first time you ever use `node-core-utils`, you will be prompted
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know it's not changed in this PR, but while you're here:

you ever use -> you have used

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The onboarding doc writes out two-factor authentication and links to the GitHub help page.

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]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the guide of node-core-utils -> the node-core-utils guide

to set up your credentials manually.

### Technical HOWTO
Expand Down
29 changes: 23 additions & 6 deletions doc/onboarding.md
View file
Open in desktop
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 to install [`node-core-utils`][] and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: remove to

[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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

team -> teams

[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`][]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: it seems [`git-node`][] URL needs updating.

command.

## Final notes

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