From e0dbb453e496b18bdac6593254b96dfbcad499aa Mon Sep 17 00:00:00 2001 From: BethGriggs Date: Tue, 15 Nov 2016 17:47:58 +0000 Subject: [PATCH] doc: remove repeated info onboarding.md COLLABORATOR_GUIDE.md and onboarding.md cover some of the same information. The aim of this commit is to remove duplicated information. PR-URL: https://github.com/nodejs/node/pull/9635 Reviewed-By: James M Snell Reviewed-By: Sam Roberts --- COLLABORATOR_GUIDE.md | 74 +++++++++++----- doc/onboarding.md | 192 ++++++++++++------------------------------ 2 files changed, 110 insertions(+), 156 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 214f262fdc61d5..702d539d460301 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -36,6 +36,8 @@ Collaborators or additional evidence that the issue has relevance, the issue may be closed. Remember that issues can always be re-opened if necessary. +[**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) + ## Accepting Modifications All modifications to the Node.js code and documentation should be @@ -60,19 +62,20 @@ and work schedules. Trivial changes (e.g. those which fix minor bugs or improve performance without affecting API or causing other wide-reaching impact) may be landed after a shorter delay. -For non-breaking changes, if there is no disagreement amongst Collaborators, a -pull request may be landed given appropriate review. Where there is discussion -amongst Collaborators, consensus should be sought if possible. The -lack of consensus may indicate the need to elevate discussion to the -CTC for resolution (see below). - -Breaking changes (that is, pull requests that require an increase in the -major version number, known as `semver-major` changes) must be elevated for -review by the CTC. This does not necessarily mean that the PR must be put onto -the CTC meeting agenda. If multiple CTC members approve (`LGTM`) the PR and no -Collaborators oppose the PR, it can be landed. Where there is disagreement among -CTC members or objections from one or more Collaborators, `semver-major` pull -requests should be put on the CTC meeting agenda. +For non-breaking changes, if there is no disagreement amongst +Collaborators, a pull request may be landed given appropriate review. +Where there is discussion amongst Collaborators, consensus should be +sought if possible. The lack of consensus may indicate the need to +elevate discussion to the CTC for resolution (see below). + +Breaking changes (that is, pull requests that require an increase in +the major version number, known as `semver-major` changes) must be +elevated for review by the CTC. This does not necessarily mean that the +PR must be put onto the CTC meeting agenda. If multiple CTC members +approve (`LGTM`) the PR and no Collaborators oppose the PR, it can be +landed. Where there is disagreement among CTC members or objections +from one or more Collaborators, `semver-major` pull requests should be +put on the CTC meeting agenda. All bugfixes require a test case which demonstrates the defect. The test should *fail* before the change, and *pass* after the change. @@ -96,13 +99,20 @@ The CTC should serve as the final arbiter where required. ## Landing Pull Requests +* Please never use GitHub's green ["Merge Pull Request"](https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-using-the-github-web-interface) button. + * If you do, please force-push removing the merge. + * Reasons for not using the web interface button: + * The merge method will add an unnecessary merge commit. + * The rebase & merge method adds metadata to the commit title. + * The rebase method changes the author. + * The squash & merge method has been known to add metadata to the + commit title. + * If more than one author has contributed to the PR, only the + latest author will be considered during the squashing. + Always modify the original commit message to include additional meta information regarding the change process: -- A `Reviewed-By: Name ` line for yourself and any - other Collaborators who have reviewed the change. - - Useful for @mentions / contact list if something goes wrong in the PR. - - Protects against the assumption that GitHub will be around forever. - A `PR-URL:` line that references the *full* GitHub URL of the original pull request being merged so it's easy to trace a commit back to the conversation that led up to that change. @@ -110,6 +120,10 @@ information regarding the change process: for an issue, and/or the hash and commit message if the commit fixes a bug in a previous commit. Multiple `Fixes:` lines may be added if appropriate. +- A `Reviewed-By: Name ` line for yourself and any + other Collaborators who have reviewed the change. + - Useful for @mentions / contact list if something goes wrong in the PR. + - Protects against the assumption that GitHub will be around forever. Review the commit message to ensure that it adheres to the guidelines outlined in the [contributing](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md#step-3-commit) guide. @@ -119,7 +133,6 @@ See the commit log for examples such as exactly how to format your commit messages. Additionally: - - Double check PRs to make sure the person's _full name_ and email address are correct before merging. - Except when updating dependencies, all commits should be self @@ -224,16 +237,36 @@ Save the file and close the editor. You'll be asked to enter a new commit message for that commit. This is a good moment to fix incorrect commit logs, ensure that they are properly formatted, and add `Reviewed-By` lines. +* The commit message text must conform to the [commit message guidelines](../CONTRIBUTING.md#step-3-commit). Time to push it: ```text $ git push origin master ``` +* Optional: Force push the amended commit to the branch you used to +open the pull request. If your branch is called `bugfix`, then the +command would be `git push --force-with-lease origin master:bugfix`. +When the pull request is closed, this will cause the pull request to +show the purple merged status rather than the red closed status that is +usually used for pull requests that weren't merged. Only do this when +landing your own contributions. + +* Close the pull request with a "Landed in ``" comment. If +your pull request shows the purple merged status then you should still +add the "Landed in .." comment if you added +multiple commits. + +* `./configure && make -j8 test` + * `-j8` builds node in parallel with 8 threads. Adjust to the number + of cores or processor-level threads your processor has (or slightly + more) for best results. ### I Just Made a Mistake -With `git`, there's a way to override remote trees by force pushing +* Ping a CTC member. +* `#node-dev` on freenode +* With `git`, there's a way to override remote trees by force pushing (`git push -f`). This should generally be seen as forbidden (since you're rewriting history on a repository other people are working against) but is allowed for simpler slip-ups such as typos in commit @@ -241,6 +274,9 @@ messages. However, you are only allowed to force push to any Node.js branch within 10 minutes from your original push. If someone else pushes to the branch or the 10 minute period passes, consider the commit final. + * Use `--force-with-lease` to minimize the chance of overwriting + someone else's change. + * Post to `#node-dev` (IRC) if you force push. ### Long Term Support diff --git a/doc/onboarding.md b/doc/onboarding.md index 5d0560e176e7ba..665890da968699 100644 --- a/doc/onboarding.md +++ b/doc/onboarding.md @@ -14,107 +14,98 @@ onboarding session. * Prior to the onboarding session, add the new Collaborators to [the Collaborators team](https://github.com/orgs/nodejs/teams/collaborators). -## **thank you** for doing this +## Onboarding session - * going to cover four things: - * local setup - * some project goals & values - * issues, labels, and reviewing code - * merging code - -## setup - - * notifications setup - * use https://github.com/notifications or set up email - * watching the main repo will flood your inbox, so be prepared +* **thank you** for doing this +* will cover: + * [local setup](#local-setup) + * [project goals & values](#project-goals--values) + * [managing the issue tracker](#managing-the-issue-tracker) + * [reviewing PRs](#reviewing-prs) + * [landing PRs](#landing-prs) +## Local setup * git: * make sure you have whitespace=fix: `git config --global --add core.whitespace fix` * usually PR from your own github fork - * [**See "Updating Node.js from Upstream"**](./onboarding-extras.md#updating-nodejs-from-upstream) + * [See "Updating Node.js from Upstream"](./onboarding-extras.md#updating-nodejs-from-upstream) * make new branches for all commits you make! + * notifications: + * use [https://github.com/notifications](https://github.com/notifications) or set up email + * watching the main repo will flood your inbox, so be prepared - * `#node-dev` on `chat.freenode.net` is the best place to interact with the CTC / other collaborators + * `#node-dev` on [webchat.freenode.net](https://webchat.freenode.net/) is the best place to interact with the CTC / other collaborators -## a little deeper about the project +## Project goals & values * collaborators are effectively part owners * the project has the goals of its contributors - * but, there are some higher-level goals and values * not everything belongs in core (if it can be done reasonably in userland, let it stay in userland) * empathy towards users matters (this is in part why we onboard people) * generally: try to be nice to people - -## managing the issue tracker +## 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 - * this will come more naturally over time - * IMPORTANT: be nice about closing issues, let people know why, and that issues and PRs can be reopened if necessary - * Still need to follow the Code of Conduct. - + * **IMPORTANT**: be nice about closing issues, let people know why, and that issues and PRs can be reopened if necessary + * Still need to follow the Code of Conduct - * Labels: + * [**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. - * [**See "Labels"**](./onboarding-extras.md#labels) * Use the `ctc-review` label if a topic is controversial or isn't coming to a conclusion after an extended time. * `semver-{minor,major}`: - * If a change has the remote *chance* of breaking something, use `semver-major` + * If a change has the remote *chance* of breaking something, use the `semver-major` label * When adding a semver label, add a comment explaining why you're adding it. Do it right away so you don't forget! - * Notifying humans - * [**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) + * [**See "Who to CC in issues"**](./onboarding-extras.md#who-to-cc-in-issues) * will also come more naturally over time - - * Reviewing: - * The primary goal is for the codebase to improve. - * Secondary (but not far off) is for the person submitting code to succeed. +## Reviewing PRs + * The primary goal is for the codebase to improve. + * Secondary (but not far off) is for the person submitting code to succeed. A pull request from a new contributor is an opportunity to grow the community. - * Review a bit at a time. Do not overwhelm new contributors. - * It is tempting to micro-optimize and make everything about relative + * Review a bit at a time. Do not overwhelm new contributors. + * It is tempting to micro-optimize and make everything about relative performance. Don't succumb to that temptation. We change V8 often. Techniques that provide improved performance today may be unnecessary in the future. - * Be aware: Your opinion carries a lot of weight! - * Nits (requests for small changes that are not essential) are fine, but try - to avoid stalling the pull request. - * Note that they are nits when you comment: `Nit: change foo() to bar().` - * If they are stalling the pull request, fix them yourself on merge. - * Minimum wait for comments time - * There is a minimum waiting time which we try to respect for non-trivial + * Be aware: Your opinion carries a lot of weight! + * Nits (requests for small changes that are not essential) are fine, but try + to avoid stalling the pull request. + * Note that they are nits when you comment: `Nit: change foo() to bar().` + * If they are stalling the pull request, fix them yourself on merge. + * Minimum wait for comments time + * There is a minimum waiting time which we try to respect for non-trivial changes, so that people who may have important input in such a distributed project are able to respond. - * For non-trivial changes, leave the pull request open for at least 48 + * For non-trivial changes, leave the pull request open for at least 48 hours (72 hours on a weekend). - * If a pull request is abandoned, check if they'd mind if you took it over + * If a pull request is abandoned, check if they'd mind if you took it over (especially if it just has nits left). - * Approving a change - * Collaborators indicate that they have reviewed and approve of the + * Approving a change + * Collaborators indicate that they have reviewed and approve of the the changes in a pull request by commenting with `LGTM`, which stands for "looks good to me". - * You have the power to `LGTM` another collaborator's (including TSC/CTC + * You have the power to `LGTM` another collaborator's (including TSC/CTC members) work. - * You may not `LGTM` your own pull requests. - * You have the power to `LGTM` anyone else's pull requests. - + * You may not `LGTM` your own pull requests. + * You have the power to `LGTM` anyone else's pull requests. - * what belongs in node: + * What belongs in node: * opinions vary, but I find the following helpful: * if node itself needs it (due to historic reasons), then it belongs in node * that is to say, url is there because of http, freelist is there because of http, et al * also, things that cannot be done outside of core, or only with significant pain (example: async-wrap) - * Continuous Integration (CI) Testing: - * https://ci.nodejs.org/ + * [https://ci.nodejs.org/](https://ci.nodejs.org/) * It is not automatically run. You need to start it manually. * Log in on CI is integrated with GitHub. Try to log in now! * You will be using `node-test-pull-request` most of the time. Go there now! @@ -130,85 +121,13 @@ onboarding session. * Use the [Build WG repo](https://github.com/nodejs/build) to file issues for the Build WG members who maintain the CI infrastructure. -## Landing PRs: Overview - - * The [Collaborator Guide](https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#technical-howto) is a great resource. - - - * No one (including TSC or CTC members) pushes directly to master without review. - * An exception is made for release commits only. - - - * One `LGTM` is sufficient, except for semver-major changes. - * More than one is better. - * Breaking changes must be LGTM'ed by at least two CTC members. - * If one or more Collaborators object to a change, it should not land until - the objection is addressed. The options for such a situation include: - * Engaging those with objections to determine a viable path forward; - * Altering the pull request to address the objections; - * Escalating the discussion to the CTC using the `ctc-review` label. This - should only be done after the previous options have been exhausted. - - * Wait before merging non-trivial changes. - * 48 hours during the week and 72 hours on weekends. - * An example of a trivial change would be correcting the misspelling of a single word in a documentation file. This sort of change still needs to receive at least one `LGTM` but it does not need to wait 48 hours before landing. - - * **Run the PR through CI before merging!** - * An exception can be made for documentation-only PRs as long as it does not include the `addons.md` documentation file. (Example code from that document is extracted and built as part of the tests!) - - * What if something goes wrong? - * Ping a CTC member. - * `#node-dev` on freenode - * Force-pushing to fix things after is allowed for ~10 minutes. Avoid it if you can. - * Use `--force-with-lease` to minimize the chance of overwriting someone else's change. - * Post to `#node-dev` (IRC) if you force push. - - -## Landing PRs: Details - -* Please never use GitHub's green ["Merge Pull Request"](https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-using-the-github-web-interface) button. - * If you do, please force-push removing the merge. - * Reasons for not using the web interface button: - * The merge method will add an unnecessary merge commit. - * The rebase & merge method adds metadata to the commit title. - * The rebase method changes the author. - * The squash & merge method has been known to add metadata to the commit title. - * If more than one author has contributed to the PR, only the latest author will be considered during the squashing. - - -Update your `master` branch (or whichever branch you are landing on, almost always `master`) - -* [**See "Updating Node.js from Upstream"**](./onboarding-extras.md#updating-nodejs-from-upstream) - -Landing a PR - -* If it all looks good, `curl -L 'url-of-pr.patch' | git am` - * If `git am` fails, see [the relevant section of the Onboarding Extras doc](./onboarding-extras.md#if-git-am-fails). -* `git rebase -i upstream/master` -* Squash into logical commits if necessary. -* `./configure && make -j8 test` (`-j8` builds node in parallel with 8 threads. adjust to the number of cores (or processor-level threads) your processor has (or slightly more) for best results.) -* Amend the commit description. - * The commit message text must conform to the [commit message guidelines](../CONTRIBUTING.md#step-3-commit). - * Add required metadata: - * `PR-URL: ` - * `Reviewed-By: ` - * Easiest to use `git log`, then do a search. - * In vim: `/Name` + `enter` (+ `n` as much as you need to) - * Only include collaborators who have commented `LGTM`. - * Add additional metadata as appropriate: - * `Fixes: ` - * Full URL of GitHub issue that the PR fixes. - * This will automatically close the PR when the commit lands in master. - * `Refs: ` - * Full URL of material that might provide additional useful information or context to someone trying to understand the change set or the thinking behind it. -* Optional: Force push the amended commit to the branch you used to open the pull request. If your branch is called `bugfix`, then the command would be `git push --force-with-lease origin master:bugfix`. When the pull request is closed, this will cause the pull request to show the purple merged status rather than the red closed status that is usually used for pull requests that weren't merged. Only do this when landing your own contributions. -* `git push upstream master` - * Close the pull request with a "Landed in ``" comment. +## Landing PRs + * [See the Collaborator Guide: Technical HOWTO](https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#technical-howto) ## Exercise: Make a PR adding yourself to the README - * Example: https://github.com/nodejs/node/commit/7b09aade8468e1c930f36b9c81e6ac2ed5bc8732 + * Example: [https://github.com/nodejs/node/commit/7b09aade8468e1c930f36b9c81e6ac2ed5bc8732](https://github.com/nodejs/node/commit/7b09aade8468e1c930f36b9c81e6ac2ed5bc8732) * For raw commit message: `git log 7b09aade8468e1c930f36b9c81e6ac2ed5bc8732 -1` * Collaborators are in alphabetical order by GitHub username. * Label your pull request with the `doc` subsystem label. @@ -216,18 +135,17 @@ Landing a PR * After a `LGTM` or two, land the PR. * Be sure to add the `PR-URL: ` and appropriate `Reviewed-By:` metadata! - -## final notes +## 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!) * very few (no?) mistakes are unrecoverable - * the existing node committers trust you and are grateful for your help! + * the existing collaborators trust you and are grateful for your help! * other repos: - * https://github.com/nodejs/dev-policy - * https://github.com/nodejs/NG - * https://github.com/nodejs/api - * https://github.com/nodejs/build - * https://github.com/nodejs/docs - * https://github.com/nodejs/nodejs.org - * https://github.com/nodejs/readable-stream - * https://github.com/nodejs/LTS + * [https://github.com/nodejs/dev-policy](https://github.com/nodejs/dev-policy) + * [https://github.com/nodejs/NG](https://github.com/nodejs/NG) + * [https://github.com/nodejs/api](https://github.com/nodejs/api) + * [https://github.com/nodejs/build](https://github.com/nodejs/build) + * [https://github.com/nodejs/docs](https://github.com/nodejs/docs) + * [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)