doc: small makeover for onboarding.md #13413
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -13,16 +13,17 @@ 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), | ||
| 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. | ||
|
|
||
|
|
||
| ## Onboarding session | ||
|
|
||
| * 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,37 @@ onboarding session. | |
| ## Local setup | ||
|
|
||
| * git: | ||
| * Make sure you have whitespace=fix: `git config --global --add apply.whitespace fix` | ||
| * Always continue to PR from your own github fork | ||
|
There was a problem hiding this comment. I don't think this is universally true - sometimes there is value in having a PR off a branch that others can easily edit. There was a problem hiding this comment. We have There was a problem hiding this comment. With the ability for collaborators to push into PR branches in forks, is that really an issue tho? There was a problem hiding this comment. There is an edge case. If the PR is against the fork's There was a problem hiding this comment.
Do you mean PR from a fork’s There was a problem hiding this comment. +1 to this, using branches in Node is not usual behaviour, we should start with the standard workflow. Maybe: - * Always continue to PR from your own github fork
+ * Continue to raise PRs from your own github forkthough |
||
| * 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 a new branch for each PR you submit. | ||
|
|
||
| * 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 | ||
|
There was a problem hiding this comment. I would add: There was a problem hiding this comment. I usually tell people that they have been subscribed to multiple repositories and may want to unsubscribe, and for most existing collaborators I think this is more or less clear. |
||
|
|
||
| * `#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` | ||
|
|
||
|
|
||
| ## Project goals & values | ||
|
|
||
| * Collaborators are the collective owners of the project | ||
| * The project has the goals of its contributors | ||
|
|
||
| * There are some higher-level goals and values | ||
| * 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 | ||
| * 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,9 +74,11 @@ 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) | ||
| * This will come more naturally over time | ||
| * For many of the teams listed there, you can ask to be added if you are interested | ||
|
There was a problem hiding this comment. Maybe also link to https://github.com/orgs/nodejs/teams ? I didn't realise that I could now see who was in what team when I was onboarded. There was a problem hiding this comment. You can’t see that page if you’re not a member, so it’s at least going to be confusing for those who read through the doc a bit in advance. There was a problem hiding this comment. Looking at this again, I see you linked to the Collaborators and members teams above, so the team listing can probably be deduced for that. |
||
| * 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. | ||
| * You can find the full moderation policy [here](https://github.com/nodejs/TSC/blob/master/Moderation-Policy.md). | ||
|
|
||
|
|
@@ -100,18 +107,24 @@ 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 using Github’s approval interface | ||
| * Some people like to comment `LGTM` (“Looks Good To Me”) | ||
|
There was a problem hiding this comment. The - the changes in a pull request using Github’s approval interface
- * Some people like to comment `LGTM` (“Looks Good To Me”)
+ the changes in a pull request using Github’s approval interface,
+ or by commenting `LGTM` (“Looks Good To Me”).There was a problem hiding this comment. The reason I prefer that method is because github does not automatically remove approvals after new changes are pushed, so having green checkmarks still show after new changes are pushed is not ideal to me. I would rather "risk" having my name left out of the 'reviewed by' list than be erroneously listed as having approved something that I didn't review. I understand it's ultimately inevitable at the time of landing, as metadata is typically landed last, but I'm mostly concerned about pushes prior to that point. There was a problem hiding this comment. @mscdex interesting point, but I'm not sure how commenting LGTM is better. If people are using the There was a problem hiding this comment. Sounds like it would be easier to fix in There was a problem hiding this comment.
Hmm okay, but doesn't that mean that those people will never record your approval at all? There was a problem hiding this comment. @gibfahn I already mentioned that I would rather chance not having my name on a PR/commit than have my name listed as having approved something I did not review. |
||
| * You have the authority to approve any other collaborator’s work. | ||
|
There was a problem hiding this comment. Maybe There was a problem hiding this comment. Reasoning: Specifying |
||
| * 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 | ||
|
There was a problem hiding this comment. Maybe also be clear that other collaborators will clear your review once the changes have been made. + * If you see that the requested changes have been made, you can clear another collaborator's
+ `Changes requested` review. |
||
| * 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! | ||
| * 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`) | ||
|
|
||
| * Continuous Integration (CI) Testing: | ||
| * [https://ci.nodejs.org/](https://ci.nodejs.org/) | ||
|
|
@@ -136,26 +149,30 @@ onboarding session. | |
|
|
||
| ## Exercise: Make a PR adding yourself to the README | ||
|
|
||
| * 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 one or two approvals, land the PR. | ||
| * Be sure to add the `PR-URL: <full-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!) | ||
| * 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) | ||
| * [https://github.com/nodejs/build](https://github.com/nodejs/build) | ||
| * [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 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe it would be better to set this only for the local node repo?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I’ve been mentioning manually sometimes that you can set this locally if you really want to… I know I would like to have this as a global option, but sure, if others don’t, I can change this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm good with this as written