Lines Matching +full:node +full:- +full:api
1 # Node.js Collaborator Guide
5 * [Issues and pull requests](#issues-and-pull-requests)
6 * [Welcoming first-time contributors](#welcoming-first-time-contributors)
7 * [Closing issues and pull requests](#closing-issues-and-pull-requests)
8 * [Author ready pull requests](#author-ready-pull-requests)
9 * [Handling own pull requests](#handling-own-pull-requests)
10 * [Accepting modifications](#accepting-modifications)
11 * [Code reviews](#code-reviews)
12 * [Consensus seeking](#consensus-seeking)
13 * [Waiting for approvals](#waiting-for-approvals)
14 * [Testing and CI](#testing-and-ci)
15 * [Useful CI jobs](#useful-ci-jobs)
16 * [Starting a CI job](#starting-a-ci-job)
17 * [Internal vs. public API](#internal-vs-public-api)
18 * [Breaking changes](#breaking-changes)
19 * [Breaking changes and deprecations](#breaking-changes-and-deprecations)
20 * [Breaking changes to internal elements](#breaking-changes-to-internal-elements)
21 * [Unintended breaking changes](#unintended-breaking-changes)
22 * [Reverting commits](#reverting-commits)
23 * [Introducing new modules](#introducing-new-modules)
24 * [Additions to N-API](#additions-to-n-api)
26 * [Involving the TSC](#involving-the-tsc)
27 * [Landing pull requests](#landing-pull-requests)
28 * [Using `git-node`](#using-git-node)
29 * [Technical HOWTO](#technical-howto)
31 * [I made a mistake](#i-made-a-mistake)
32 * [Long term support](#long-term-support)
33 * [What is LTS?](#what-is-lts)
34 * [How are LTS branches managed?](#how-are-lts-branches-managed)
35 * [How can I help?](#how-can-i-help)
36 * [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker)
38 This document explains how Collaborators manage the Node.js project.
47 request. See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker).
49 ### Welcoming first-time contributors
52 welcoming to first-time contributors, identified by the GitHub
53  badge.
55 For first-time contributors, check if the commit author is the same as the pull
58 [username][git-username] and [email][git-email] to their liking.
63 future of the Node.js project. Where this is unclear, leave the issue or pull
66 issues and pull requests can always be re-opened if necessary.
81 When you open a pull request, [start a CI](#testing-and-ci) right away. Later,
86 to land but is [author ready](#author-ready-pull-requests), add the
88 "assign yourself" link to self-assign it.
92 Contributors propose modifications to Node.js using GitHub pull requests. This
108 for review by @-mention.
109 See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker).
112 please [start one](#testing-and-ci). Please also start a new CI if the
117 A pull request can land if it has the needed [approvals](#code-reviews),
118 [CI](#testing-and-ci), [wait time](#waiting-for-approvals) and no
119 [outstanding objections](#objections). [Breaking changes](#breaking-changes)
120 must receive [TSC review](#involving-the-tsc) in addition to other
122 [wait time](#waiting-for-approvals), please add the
123 [`author ready`](#author-ready-pull-requests) label.
143 adding the `tsc-agenda` label to the issue.
147 * [How to Do Code Reviews Like a Human (Part One)](https://mtlynch.io/human-code-reviews-1/)
148 * [How to Do Code Reviews Like a Human (Part Two)](https://mtlynch.io/human-code-reviews-2/)
149 * [Code Review Etiquette](https://css-tricks.com/code-review-etiquette/)
154 Certain types of pull requests can be fast-tracked and can land after a shorter
158 * `code-and-learn` tasks often fall into this category.
159 * `good-first-issue` pull requests might also be suitable.
164 To propose fast-tracking a pull request, apply the `fast-track` label. Then add
167 If someone disagrees with the fast-tracking request, remove the label. Do not
168 fast-track the pull request in that case.
170 The pull request can be fast-tracked if two Collaborators approve the
171 fast-tracking request. To land, the pull request itself still needs two
174 Collaborators can request fast-tracking of pull requests they did not author.
175 In that case only, the request itself is also one fast-track approval. Upvote
188 For documentation-only changes, GitHub Actions CI is sufficient.
191 Build". It is in the left navigation of the relevant `node-test-pull-request`
192 job. It will preserve all the green results from the current job but re-run
199 * [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/)
200 is the CI job to test pull requests. It runs the `build-ci` and `test-ci`
203 * [`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/)
208 * [`node-stress-single-test`](https://ci.nodejs.org/job/node-stress-single-test/)
212 * [`node-test-commit-v8-linux`](https://ci.nodejs.org/job/node-test-commit-v8-linux/)
213 runs the standard V8 tests. Run it when updating V8 in Node.js or floating new
216 * [`node-test-commit-custom-suites-freestyle`](https://ci.nodejs.org/job/node-test-commit-custom-su…
220 used in other CI test runs (such as `--worker`).
231 (e.g. for `master` -> `refs/heads/master`).
233 (e.g. for PR#42 -> `refs/pull/42/head`).
244 [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/)
247 ### Internal vs. public API
249 All functionality in the official Node.js documentation is part of the public
250 API. Any undocumented object, property, method, argument, behavior, or event is
251 internal. There are exceptions to this rule. Node.js users have come to rely on
258 public, though, if it is re-exported by code in `lib/*.js`.
260 Non-exported `Symbol` properties and methods are internal.
270 For undocumented APIs that are public, open a pull request documenting the API.
274 At least two TSC members must approve backward-incompatible changes to the
279 * Removal or redefinition of existing API arguments.
284 * Changing the side effects of using a particular API.
288 Existing stable public APIs that change in a backward-incompatible way must
291 * Adding or removing errors thrown or reported by a public API.
293 * Altering the timing and non-internal side effects of the public API.
294 * Changes to errors thrown by dependencies of Node.js, such as V8.
295 * One-time exceptions granted by the TSC.
301 Breaking changes to internal elements can occur in semver-patch or semver-minor
305 If a change will cause ecosystem breakage, then it is semver-major. Consider
306 providing a Public API in such cases.
310 Sometimes, a change intended to be non-breaking turns out to be a breaking
312 it. As an alternative to reverting, the TSC can apply the semver-major label
313 after-the-fact.
337 * Land only after sign-off from at least two TSC members.
339 Experimental until a semver-major release.
341 ### Additions to N-API
343 N-API provides an ABI-stable API guaranteed for future Node.js versions. N-API
346 guide](https://github.com/nodejs/node/blob/master/doc/guides/adding-new-napi-api.md).
350 Node.js uses three [Deprecation][] levels. For all deprecated APIs, the API
353 * Documentation-Only Deprecation
354 * A deprecation notice appears in the API documentation.
358 * Might cause a runtime warning with the [`--pending-deprecation`][] flag or
362 * Emits a warning at runtime on first use of the deprecated API.
363 * If used with the [`--throw-deprecation`][] flag, will throw a runtime error.
365 * End-of-Life
366 * The API is no longer subject to the semantic versioning rules.
367 * Backward-incompatible changes including complete removal of such APIs can
371 Documentation-Only Deprecations. Such deprecations have no impact on code
372 execution. Thus, they are not breaking changes (`semver-major`).
374 Runtime Deprecations and End-of-Life APIs (internal or public) are breaking
375 changes (`semver-major`). The TSC can make exceptions, deciding that one of
378 Avoid Runtime Deprecations when an alias or a stub/no-op will suffice. An alias
379 or stub will have lower maintenance costs for end users and Node.js core.
383 documentation for the deprecation identifier must always remain in the API
385 example, due to removal of an End-of-Life deprecated API).
387 <a id="deprecation-cycle"></a>
388 A _deprecation cycle_ is a major release during which an API has been in one of
389 the three Deprecation levels. Documentation-Only Deprecations can land in a
393 No API can change to End-of-Life without going through a Runtime Deprecation
394 cycle. There is no rule that deprecated code must progress to End-of-Life.
395 Documentation-Only and Runtime Deprecations can remain in place for an unlimited
402 Use the `notable-change` label on pull requests that add or change the
403 deprecation level of an API.
410 * Is labeled `semver-major`, or
415 @-mention the `@nodejs/tsc` GitHub team if you want to elevate an issue to the
416 [TSC][]. Do not use the GitHub UI on the right-hand side to assign to
424 who wish to land their own pull requests will self-assign them. Sometimes, an
436 issues in the [node][unreliable tests] or
442 as a reference. See [this commit][commit-example] as an example.
444 For pull requests from first-time contributors, be
445 [welcoming](#welcoming-first-time-contributors). Also, verify that their git
448 All commits should be self-contained, meaning every commit should pass all
451 ### Using `git-node`
453 In most cases, using [the `git-node` command][git-node] of [`node-core-utils`][]
455 this tool, please file an issue [to the issue tracker][node-core-utils-issues].
460 $ npm install -g node-core-utils
461 $ git node land $PRID
464 To use `node-core-utils`, you will need a GitHub access token. If you do not
465 have one, `node-core-utils` will create one for you the first time you use it.
466 To do this, it will ask for your GitHub password and two-factor authentication
468 [the `node-core-utils` guide][node-core-utils-credentials].
473 pull request rather than rely on `git-node`.
481 $ git am --abort
482 $ git rebase --abort
492 [CONTRIBUTING.md](./contributing/pull-requests.md#step-1-fork)):
496 $ git merge --ff-only upstream/master
502 $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix
505 If the merge fails even though recent CI runs were successful, try a 3-way
509 $ git am --abort
510 $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix
513 If the 3-way merge succeeds, check the results against the original pull
516 If the 3-way merge fails, then it is most likely that a conflicting pull request
519 Check and re-review the changes:
534 $ git rebase -i upstream/master
555 # These lines can be re-ordered; they are executed from top to bottom.
588 [`git node metadata`][git-node-metadata] command can generate the metadata
591 * Required: A `PR-URL:` line that references the full GitHub URL of the pull
598 * Required: A `Reviewed-By: Name <email>` line for each Collaborator who
605 precaution, run tests (`make -j4 test` or `vcbuild test`).
608 [core-validate-commit](https://github.com/evanlucas/core-validate-commit).
611 $ git rev-list upstream/master...HEAD | xargs core-validate-commit
616 --force-with-lease origin master:bugfix`. Don't close the pull request.
643 To https://github.com/nodejs/node
644 ! [rejected] master -> master (fetch first)
645 error: failed to push some refs to 'https://github.com/nodejs/node'
649 hint: See the 'Note about fast-forwards' in 'git push --help' for details.
657 git pull upstream master --rebase
658 make -j4 test
665 * `#node-dev` on freenode.
667 (`git push -f`). This is generally forbidden as it creates conflicts in other
668 people's forks. It is permissible for simpler slip-ups such as typos in commit
669 messages. You are only allowed to force push to any Node.js branch within 10
671 10-minute period passes, consider the commit final.
672 * Use `--force-with-lease` to reduce the chance of overwriting someone else's
674 * Post to `#node-dev` (IRC) if you force push.
680 Long Term Support (LTS) guarantees 30-month support cycles for specific Node.js
682 [in the full release plan](https://github.com/nodejs/Release#release-plan). Once
689 corresponding staging branch (v10.x-staging, v8.x-staging, etc.).
691 Commits that land on master are cherry-picked to each staging branch as
706 There are several LTS-related labels:
708 * `lts-watch-` labels are for pull requests to consider for landing in staging
709 branches. For example, `lts-watch-v10.x` would be for a change
710 to consider for the `v10.x-staging` branch.
712 * `land-on-` are for pull requests that should land in a future v*.x
713 release. For example, `land-on-v10.x` would be for a change to land in Node.js
717 land on the staging branches, the backporter removes the `lts-watch-` label.
718 Likewise, as commits land in an LTS release, the releaser removes the `land-on-`
721 Attach the appropriate `lts-watch-` label to any pull request that
727 | --- | --- …
731 …s` | @nodejs/async\_hooks for bugs/reviews (+ @nodejs/diagnostics for API) |
740 | `lib/inspector.js`, `src/inspector_*` | @nodejs/v8-inspector …
750 | `src/node_api.*` | @nodejs/n-api …
758 | platform specific | @nodejs/platform-{aix,arm,freebsd,macos,ppc,smartos,s3…
760 | upgrading c-ares | @rvagg …
761 | upgrading http-parser | @nodejs/http, @nodejs/http2 …
764 | upgrading V8 | @nodejs/V8, @nodejs/post-mortem …
765 | Embedded use or delivery of Node.js | @nodejs/delivery-channels …
767 When things need extra attention, are controversial, or `semver-major`:
770 If you cannot find who to cc for a file, `git shortlog -n -s <file>` can help.
772 …ull Request"]: https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-on-…
774 [Stability Index]: ../api/documentation.md#stability-index
776 [`--pending-deprecation`]: ../api/cli.md#--pending-deprecation
777 [`--throw-deprecation`]: ../api/cli.md#--throw-deprecation
778 [`node-core-utils`]: https://github.com/nodejs/node-core-utils
779 [backporting guide]: backporting-to-release-lines.md
780 [commit message guidelines]: contributing/pull-requests.md#commit-message-guidelines
781 [commit-example]: https://github.com/nodejs/node/commit/b636ba8186
782 [git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/
783 [git-node]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md
784 [git-node-metadata]: https://github.com/nodejs/node-core-utils/blob/master/docs/git-node.md#git-nod…
785 [git-username]: https://help.github.com/articles/setting-your-username-in-git/
786 [node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
787 [node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues
788 [unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+…