1# Onboarding 2 3This document is an outline of the things we tell new Collaborators at their 4onboarding session. 5 6## One week before the onboarding session 7 8* If the new Collaborator is not yet a member of the nodejs GitHub organization, 9 confirm that they are using [two-factor authentication][]. It will not be 10 possible to add them to the organization if they are not using two-factor 11 authentication. If they cannot receive SMS messages from GitHub, try 12 [using a TOTP mobile app][]. 13* Announce the accepted nomination in a TSC meeting and in the TSC 14 mailing list. 15* Suggest the new Collaborator install [`node-core-utils`][] and 16 [set up the credentials][] for it. 17 18## Fifteen minutes before the onboarding session 19 20* Prior to the onboarding session, add the new Collaborator to 21 [the Collaborators team](https://github.com/orgs/nodejs/teams/collaborators). 22* Ask them if they want to join any subsystem teams. See 23 [Who to CC in the issue tracker][who-to-cc]. 24 25## Onboarding session 26 27* This session will cover: 28 * [local setup](#local-setup) 29 * [project goals & values](#project-goals--values) 30 * [managing the issue tracker](#managing-the-issue-tracker) 31 * [reviewing PRs](#reviewing-prs) 32 * [landing PRs](#landing-prs) 33 34## Local setup 35 36* git: 37 * Make sure you have whitespace=fix: `git config --global --add 38 apply.whitespace fix` 39 * Always continue to PR from your own GitHub fork 40 * Branches in the `nodejs/node` repository are only for release lines 41 * Add the canonical nodejs repository as `upstream` remote: 42 * `git remote add upstream git://github.com/nodejs/node.git` 43 * To update from `upstream`: 44 * `git checkout master` 45 * `git remote update -p` OR `git fetch --all` 46 * `git merge --ff-only upstream/master` (or `REMOTENAME/BRANCH`) 47 * Make a new branch for each PR you submit. 48 * Membership: Consider making your membership in the Node.js GitHub 49 organization public. This makes it easier to identify Collaborators. 50 Instructions on how to do that are available at 51 [Publicizing or hiding organization membership][]. 52 53* Notifications: 54 * Use [https://github.com/notifications](https://github.com/notifications) or 55 set up email 56 * Watching the main repo will flood your inbox (several hundred notifications 57 on typical weekdays), so be prepared 58 59The project has two venues for real-time discussion: 60* [`#nodejs-dev`](https://openjs-foundation.slack.com/archives/C019Y2T6STH) on 61 the [OpenJS Foundation](https://slack-invite.openjsf.org/) 62* `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is a 63 great place to interact with the TSC and other Collaborators 64 * If there are any questions after the session, a good place to ask is 65 there! 66 * Presence is not mandatory, but please drop a note there if force-pushing 67 to `master` 68 69## Project goals & values 70 71* Collaborators are the collective owners of the project 72 * The project has the goals of its contributors 73 74* There are some higher-level goals and values 75 * Empathy towards users matters (this is in part why we onboard people) 76 * Generally: try to be nice to people! 77 * The best outcome is for people who come to our issue tracker to feel like 78 they can come back again. 79 80* You are expected to follow *and* hold others accountable to the 81 [Code of Conduct][]. 82 83## Managing the issue tracker 84 85* You have (mostly) free rein; don't hesitate to close an issue if you are 86 confident that it should be closed 87 * Be nice about closing issues! Let people know why, and that issues and PRs 88 can be reopened if necessary 89 90* [**See "Labels"**](./doc/guides/onboarding-extras.md#labels) 91 * There is [a bot](https://github.com/nodejs-github-bot/github-bot) that 92 applies subsystem labels (for example, `doc`, `test`, `assert`, or `buffer`) 93 so that we know what parts of the code base the pull request modifies. It is 94 not perfect, of course. Feel free to apply relevant labels and remove 95 irrelevant labels from pull requests and issues. 96 * `semver-{minor,major}`: 97 * If a change has the remote *chance* of breaking something, use the 98 `semver-major` label 99 * When adding a `semver-*` label, add a comment explaining why you're adding 100 it. Do it right away so you don't forget! 101 * Please add the [`author-ready`][] label for PRs, if applicable. 102 103* See [Who to CC in the issue tracker][who-to-cc]. 104 * This will come more naturally over time 105 * For many of the teams listed there, you can ask to be added if you are 106 interested 107 * Some are WGs with some process around adding people, others are only there 108 for notifications 109 110* When a discussion gets heated, you can request that other Collaborators keep 111 an eye on it by opening an issue at the private 112 [nodejs/moderation](https://github.com/nodejs/moderation) repository. 113 * This is a repository to which all members of the `nodejs` GitHub 114 organization (not just Collaborators on Node.js core) have access. Its 115 contents should not be shared externally. 116 * You can find the full moderation policy 117 [here](https://github.com/nodejs/admin/blob/master/Moderation-Policy.md). 118 119## Reviewing PRs 120 121* The primary goal is for the codebase to improve. 122* Secondary (but not far off) is for the person submitting code to succeed. A 123 pull request from a new contributor is an opportunity to grow the community. 124* Review a bit at a time. Do not overwhelm new contributors. 125 * It is tempting to micro-optimize. Don't succumb to that temptation. We 126 change V8 often. Techniques that provide improved performance today may be 127 unnecessary in the future. 128* Be aware: Your opinion carries a lot of weight! 129* Nits (requests for small changes that are not essential) are fine, but try to 130 avoid stalling the pull request. 131 * Identify them as nits when you comment: `Nit: change foo() to bar().` 132 * If they are stalling the pull request, fix them yourself on merge. 133* Insofar as possible, issues should be identified by tools rather than human 134 reviewers. If you are leaving comments about issues that could be identified 135 by tools but are not, consider implementing the necessary tooling. 136* Minimum wait for comments time 137 * There is a minimum waiting time which we try to respect for non-trivial 138 changes so that people who may have important input in such a distributed 139 project are able to respond. 140 * For non-trivial changes, leave the pull request open for at least 48 hours. 141 * If a pull request is abandoned, check if they'd mind if you took it over 142 (especially if it just has nits left). 143* Approving a change 144 * Collaborators indicate that they have reviewed and approve of the changes in 145 a pull request using GitHub’s approval interface 146 * Some people like to comment `LGTM` (“Looks Good To Me”) 147 * You have the authority to approve any other collaborator’s work. 148 * You cannot approve your own pull requests. 149 * When explicitly using `Changes requested`, show empathy – comments will 150 usually be addressed even if you don’t use it. 151 * If you do, it is nice if you are available later to check whether your 152 comments have been addressed 153 * If you see that the requested changes have been made, you can clear 154 another collaborator's `Changes requested` review. 155 * Use `Changes requested` to indicate that you are considering some of your 156 comments to block the PR from landing. 157 158* What belongs in Node.js: 159 * Opinions vary – it’s good to have a broad collaborator base for that reason! 160 * If Node.js itself needs it (due to historical reasons), then it belongs in 161 Node.js. 162 * That is to say, `url` is there because of `http`, `freelist` is there 163 because of `http`, etc. 164 * Things that cannot be done outside of core, or only with significant pain 165 such as `async_hooks`. 166 167* Continuous Integration (CI) Testing: 168 * [https://ci.nodejs.org/](https://ci.nodejs.org/) 169 * It is not automatically run. You need to start it manually. 170 * Log in on CI is integrated with GitHub. Try to log in now! 171 * You will be using `node-test-pull-request` most of the time. Go there now! 172 * Consider bookmarking it: <https://ci.nodejs.org/job/node-test-pull-request/> 173 * To get to the form to start a job, click on `Build with Parameters`. (If you 174 don't see it, that probably means you are not logged in!) Click it now! 175 * To start CI testing from this screen, you need to fill in two elements on 176 the form: 177 * The `CERTIFY_SAFE` box should be checked. By checking it, you are 178 indicating that you have reviewed the code you are about to test and you 179 are confident that it does not contain any malicious code. (We don't want 180 people hijacking our CI hosts to attack other hosts on the internet, for 181 example!) 182 * The `PR_ID` box should be filled in with the number identifying the pull 183 request containing the code you wish to test. For example, if the URL for 184 the pull request is `https://github.com/nodejs/node/issues/7006`, then put 185 `7006` in the `PR_ID`. 186 * The remaining elements on the form are typically unchanged. 187 * If you need help with something CI-related: 188 * Use #node-dev (IRC) to talk to other Collaborators. 189 * Use #node-build (IRC) to talk to the Build WG members who maintain the CI 190 infrastructure. 191 * Use the [Build WG repo](https://github.com/nodejs/build) to file issues 192 for the Build WG members who maintain the CI infrastructure. 193 194## Landing PRs 195 196See the Collaborator Guide: [Landing Pull Requests][]. 197 198Commits in one PR that belong to one logical change should 199be squashed. It is rarely the case in onboarding exercises, so this 200needs to be pointed out separately during the onboarding. 201 202<!-- TODO(joyeechueng): provide examples about "one logical change" --> 203 204## Exercise: Make a PR adding yourself to the README 205 206* Example: 207 <https://github.com/nodejs/node/commit/ce986de829457c39257cd205067602e765768fb0> 208 * For raw commit message: `git log ce986de829457c39257cd205067602e765768fb0 209 -1` 210* Collaborators are in alphabetical order by GitHub username. 211* Optionally, include your personal pronouns. 212* Label your pull request with the `doc`, `notable-change`, and `fast-track` 213 labels. 214* Run CI on the PR. Use the `node-test-pull-request` CI task. 215* After two Collaborator approvals for the change and two Collaborator approvals 216 for fast-tracking, land the PR. 217* Leave a comment in the PR: `Please �� this comment to approve fast-tracking`. 218* If there are not enough approvals within a reasonable time, consider the 219 single approval of the onboarding TSC member sufficient, and land the PR. 220 * Be sure to add the `PR-URL: <full-pr-url>` and appropriate `Reviewed-By:` 221 metadata. 222 * [`node-core-utils`][] automates the generation of metadata and the landing 223 process. See the documentation of [`git-node`][]. 224 * [`core-validate-commit`][] automates the validation of commit messages. 225 This will be run during `git node land --final` of the [`git-node`][] 226 command. 227 228## Final notes 229 230* Don't worry about making mistakes: everybody makes them, there's a lot to 231 internalize and that takes time (and we recognize that!) 232* Almost any mistake you could make can be fixed or reverted. 233* The existing Collaborators trust you and are grateful for your help! 234* Other repositories: 235 * [https://github.com/nodejs/TSC](https://github.com/nodejs/TSC) 236 * [https://github.com/nodejs/build](https://github.com/nodejs/build) 237 * [https://github.com/nodejs/nodejs.org](https://github.com/nodejs/nodejs.org) 238 * [https://github.com/nodejs/readable-stream](https://github.com/nodejs/readable-stream) 239 * [https://github.com/nodejs/LTS](https://github.com/nodejs/LTS) 240 * [https://github.com/nodejs/citgm](https://github.com/nodejs/citgm) 241* The OpenJS Foundation hosts regular summits for active contributors to the 242 Node.js project, where we have face-to-face discussions about our work on the 243 project. The Foundation has travel funds to cover participants' expenses 244 including accommodations, transportation, visa fees, etc. if needed. Check out 245 the [summit](https://github.com/nodejs/summit) repository for details. 246 247[Code of Conduct]: https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md 248[Landing Pull Requests]: doc/guides/collaborator-guide.md#landing-pull-requests 249[Publicizing or hiding organization membership]: https://help.github.com/articles/publicizing-or-hiding-organization-membership/ 250[`author-ready`]: doc/guides/collaborator-guide.md#author-ready-pull-requests 251[`core-validate-commit`]: https://github.com/nodejs/core-validate-commit 252[`git-node`]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md 253[`node-core-utils`]: https://github.com/nodejs/node-core-utils 254[set up the credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials 255[two-factor authentication]: https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ 256[using a TOTP mobile app]: https://help.github.com/articles/configuring-two-factor-authentication-via-a-totp-mobile-app/ 257[who-to-cc]: doc/guides/collaborator-guide.md#who-to-cc-in-the-issue-tracker 258