From 49b4f0d54e53c0d363009fedb1b606fd5ed6e2b9 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Thu, 19 Nov 2015 13:53:43 +1100 Subject: [PATCH] doc: backport README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/3642 Reviewed-By: Johan Bergström --- README.md | 416 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 312 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index acaf24b372cb30..435ced8d6864f5 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,197 @@ -Evented I/O for V8 javascript. -=== +Node.js +======= + +[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/nodejs/node?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +The Node.js project is supported by the +[Node.js Foundation](https://nodejs.org/en/foundation/). Contributions, +policies and releases are managed under an +[open governance model](./GOVERNANCE.md). We are also bound by a +[Code of Conduct](./CODE_OF_CONDUCT.md). + +If you need help using or installing Node.js, please use the +[nodejs/help](https://github.com/nodejs/help) issue tracker. + +## Release Types + +The Node.js project maintains multiple types of releases: + +* **Stable**: Released from active development branches of this repository, + versioned by [SemVer](http://semver.org/) and signed by a member of the + [Release Team](#release-team). + Code for Stable releases is organized in this repository by major version + number, For example: [v4.x](https://github.com/nodejs/node/tree/v4.x). + The major version number of Stable releases will increment every 6 months + allowing for breaking changes to be introduced. This happens in April and + October every year. Stable release lines beginning in October each year have + a maximum support life of 8 months. Stable release lines beginning in April + each year will convert to LTS (see below) after 6 months and receive further + support for 30 months. +* **LTS**: Releases that receive Long-term Support, with a focus on stability + and security. Every second Stable release line (major version) will become an + LTS line and receive 18 months of _Active LTS_ support and a further 12 + months of _Maintenance_. LTS release lines are given alphabetically + ordered codenames, begining with v4 Argon. LTS releases are less frequent + and will attempt to maintain consistent major and minor version numbers, + only incrementing patch version numbers. There are no breaking changes or + feature additions, except in some special circumstances. More information + can be found in the [LTS README](https://github.com/nodejs/LTS/). +* **Nightly**: Versions of code in this repository on the current Stable + branch, automatically built every 24-hours where changes exist. Use with + caution. + +## Download + +Binaries, installers, and source tarballs are available at +. + +**Stable** and **LTS** releases are available at +, listed under their version strings. +The [latest](https://nodejs.org/download/release/latest/) directory is an +alias for the latest Stable release. The latest LTS release from an LTS +line is available in the form: latest-lts-_codename_. For example: + + +**Nightly** builds are available at +, listed under their version +string which includes their date (in UTC time) and the commit SHA at +the HEAD of the release. + +**API documentation** is available in each release and nightly +directory under _docs_. points to the API +documentation of the latest stable version. + +### Verifying Binaries + +Stable, LTS and Nightly download directories all contain a *SHASUM256.txt* +file that lists the SHA checksums for each file available for +download. To check that a downloaded file matches the checksum, run +it through `sha256sum` with a command such as: -### To build: +``` +$ grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - +``` -Prerequisites (Unix only): +_(Where "node-vx.y.z.tar.gz" is the name of the file you have +downloaded)_ - * GCC 4.2 or newer - * G++ 4.2 or newer - * Python 2.6 or 2.7 - * GNU Make 3.81 or newer - * libexecinfo (FreeBSD and OpenBSD only) +Additionally, Stable and LTS releases (not Nightlies) have GPG signed +copies of SHASUM256.txt files available as SHASUM256.txt.asc. You can use +`gpg` to verify that the file has not been tampered with. -Unix/Macintosh: +To verify a SHASUM256.txt.asc, you will first need to import all of +the GPG keys of individuals authorized to create releases. They are +listed at the bottom of this README under [Release Team](#release-team). +Use a command such as this to import the keys: -```sh -./configure -make -make install ``` +$ gpg --keyserver pool.sks-keyservers.net \ + --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D +``` + +_(See the bottom of this README for a full script to import active +release keys)_ + +You can then use `gpg --verify SHASUMS256.txt.asc` to verify that the +file has been signed by an authorized member of the Node.js team. + +Once verified, use the SHASUMS256.txt.asc file to get the checksum for +the binary verification command above. + +## Build -If your python binary is in a non-standard location or has a +### Unix / Macintosh + +Prerequisites: + +* GCC 4.2 or newer +* G++ 4.2 or newer +* Python 2.6 or 2.7 +* GNU Make 3.81 or newer +* libexecinfo (FreeBSD and OpenBSD only) + +```text +$ ./configure +$ make +$ [sudo] make install +``` + +If your Python binary is in a non-standard location or has a non-standard name, run the following instead: -```sh -export PYTHON=/path/to/python -$PYTHON ./configure -make -make install +```text +$ export PYTHON=/path/to/python +$ $PYTHON ./configure +$ make +$ [sudo] make install ``` -Prerequisites (Windows only): +To run the tests: - * Python 2.6 or 2.7 - * Visual Studio 2010 or 2012 +```text +$ make test +``` -Windows: +To build the documentation: -```sh -vcbuild nosign +```text +$ make doc ``` -You can download pre-built binaries for various operating systems from -[http://nodejs.org/download/](http://nodejs.org/download/). The Windows -and OS X installers will prompt you for the location in which to install. -The tarballs are self-contained; you can extract them to a local directory -with: +To read the documentation: -```sh -tar xzf /path/to/node---.tar.gz +```text +$ man doc/node.1 ``` -Or system-wide with: +To test if Node.js was built correctly: -```sh -cd /usr/local && tar --strip-components 1 -xzf \ - /path/to/node---.tar.gz +``` +$ node -e "console.log('Hello from node.js ' + process.version)" ``` -### To run the tests: +### Windows -Unix/Macintosh: +Prerequisites: -```sh -make test +* [Python 2.6 or 2.7](https://www.python.org/downloads/) +* Visual Studio 2010 or 2012; or +* Visual Studio 2013 for Windows Desktop; or +* Visual Studio Express 2013 for Windows Desktop +* Basic Unix tools required for some tests, + [Git for Windows](http://git-scm.com/download/win) includes Git Bash + and tools which can be included in the global `PATH`. + +```text +> vcbuild nosign ``` -Windows: +To run the tests: -```sh -vcbuild test +```text +> vcbuild test ``` -### To build the documentation: +To test if Node.js was built correctly: -```sh -make doc ``` +$ node -e "console.log('Hello from node.js ' + process.version)" +``` + +### Android / Android based devices, aka. Firefox OS -### To read the documentation: +Be sure you have downloaded and extracted [Android NDK] +(https://developer.android.com/tools/sdk/ndk/index.html) +before in a folder. Then run: -```sh -man doc/node.1 +``` +$ ./android-configure /path/to/your/android-ndk +$ make ``` ### `Intl` (ECMA-402) support: -[Intl](https://github.com/joyent/node/wiki/Intl) support is not +[Intl](https://github.com/nodejs/node/wiki/Intl) support is not enabled by default. #### "small" (English only) support @@ -94,64 +200,67 @@ This option will build with "small" (English only) support, but the full `Intl` (ECMA-402) APIs. With `--download=all` it will download the ICU library as needed. -Unix/Macintosh: +Unix / Macintosh: -```sh -./configure --with-intl=small-icu --download=all +```text +$ ./configure --with-intl=small-icu --download=all ``` Windows: -```sh -vcbuild small-icu download-all +```text +> vcbuild small-icu download-all ``` -The `small-icu` mode builds -with English-only data. You can add full data at runtime. +The `small-icu` mode builds with English-only data. You can add full +data at runtime. *Note:* more docs are on -[the wiki](https://github.com/joyent/node/wiki/Intl). +[the node wiki](https://github.com/nodejs/node/wiki/Intl). #### Build with full ICU support (all locales supported by ICU): -With the `--download=all`, this may download ICU if you don't -have an ICU in `deps/icu`. +With the `--download=all`, this may download ICU if you don't have an +ICU in `deps/icu`. -Unix/Macintosh: +Unix / Macintosh: -```sh -./configure --with-intl=full-icu --download=all +```text +$ ./configure --with-intl=full-icu --download=all ``` Windows: -```sh -vcbuild full-icu download-all +```text +> vcbuild full-icu download-all ``` #### Build with no Intl support `:-(` -The `Intl` object will not be available. -This is the default at present, so this option is not normally needed. +The `Intl` object will not be available. This is the default at +present, so this option is not normally needed. -Unix/Macintosh: +Unix / Macintosh: -```sh -./configure --with-intl=none +```text +$ ./configure --with-intl=none ``` Windows: -```sh -vcbuild intl-none +```text +> vcbuild intl-none ``` -#### Use existing installed ICU (Unix/Macintosh only): +#### Use existing installed ICU (Unix / Macintosh only): -```sh -pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu +```text +$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu ``` +If you are cross compiling, your `pkg-config` must be able to supply a path +that works for both your host and target environments. + #### Build with a specific ICU: You can find other ICU releases at @@ -159,42 +268,141 @@ You can find other ICU releases at Download the file named something like `icu4c-**##.#**-src.tgz` (or `.zip`). -Unix/Macintosh: from an already-unpacked ICU +Unix / Macintosh -```sh -./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu -``` +```text +# from an already-unpacked ICU: +$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu -Unix/Macintosh: from a local ICU tarball +# from a local ICU tarball +$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz -```sh -./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz +# from a tarball URL +$ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz ``` -Unix/Macintosh: from a tarball URL +Windows + +First unpack latest ICU to `deps/icu` +[icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`) +as `deps/icu` (You'll have: `deps/icu/source/...`) -```sh -./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz +```text +> vcbuild full-icu ``` -Windows: first unpack latest ICU to `deps/icu` - [icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`) - as `deps/icu` (You'll have: `deps/icu/source/...`) +## Resources for Newcomers + +* [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) +* [CONTRIBUTING.md](./CONTRIBUTING.md) +* [GOVERNANCE.md](./GOVERNANCE.md) +* IRC: + [#io.js on Freenode.net](http://webchat.freenode.net?channels=io.js&uio=d4) +* [nodejs/node on Gitter](https://gitter.im/nodejs/node) + +## Security + +All security bugs in node.js are taken seriously and should be reported by +emailing security@nodejs.org. This will be delivered to a subset of the project +team who handle security issues. Please don't disclose security bugs +public until they have been handled by the security team. + +Your email will be acknowledged within 24 hours, and you’ll receive a more +detailed response to your email within 48 hours indicating the next steps in +handling your report. + +## Current Project Team Members + +The Node.js project team comprises a group of core collaborators and a sub-group +that forms the _Technical Steering Committee_ (TSC) which governs the project. For more +information about the governance of the Node.js project, see +[GOVERNANCE.md](./GOVERNANCE.md). + +### TSC (Technical Steering Committee) + +* [bnoordhuis](https://github.com/bnoordhuis) - **Ben Noordhuis** <info@bnoordhuis.nl> +* [chrisdickinson](https://github.com/chrisdickinson) - **Chris Dickinson** <christopher.s.dickinson@gmail.com> +* [cjihrig](https://github.com/cjihrig) - **Colin Ihrig** <cjihrig@gmail.com> +* [fishrock123](https://github.com/fishrock123) - **Jeremiah Senkpiel** <fishrock123@rocketmail.com> +* [indutny](https://github.com/indutny) - **Fedor Indutny** <fedor.indutny@gmail.com> +* [jasnell](https://github.com/jasnell) - **James M Snell** <jasnell@gmail.com> +* [misterdjules](https://github.com/misterdjules) - **Julien Gilli** <jgilli@nodejs.org> +* [mscdex](https://github.com/mscdex) - **Brian White** <mscdex@mscdex.net> +* [orangemocha](https://github.com/orangemocha) - **Alexis Campailla** <orangemocha@nodejs.org> +* [piscisaureus](https://github.com/piscisaureus) - **Bert Belder** <bertbelder@gmail.com> +* [rvagg](https://github.com/rvagg) - **Rod Vagg** <rod@vagg.org> +* [shigeki](https://github.com/shigeki) - **Shigeki Ohtsu** <ohtsu@iij.ad.jp> +* [trevnorris](https://github.com/trevnorris) - **Trevor Norris** <trev.norris@gmail.com> + +### Collaborators + +* [brendanashworth](https://github.com/brendanashworth) - **Brendan Ashworth** <brendan.ashworth@me.com> +* [ChALkeR](https://github.com/ChALkeR) - **Сковорода Никита Андреевич** <chalkerx@gmail.com> +* [domenic](https://github.com/domenic) - **Domenic Denicola** <d@domenic.me> +* [evanlucas](https://github.com/evanlucas) - **Evan Lucas** <evanlucas@me.com> +* [geek](https://github.com/geek) - **Wyatt Preul** <wpreul@gmail.com> +* [isaacs](https://github.com/isaacs) - **Isaac Z. Schlueter** <i@izs.me> +* [jbergstroem](https://github.com/jbergstroem) - **Johan Bergström** <bugs@bergstroem.nu> +* [joaocgreis](https://github.com/joaocgreis) - **João Reis** <reis@janeasystems.com> +* [julianduque](https://github.com/julianduque) - **Julian Duque** <julianduquej@gmail.com> +* [lxe](https://github.com/lxe) - **Aleksey Smolenchuk** <lxe@lxe.co> +* [mhdawson](https://github.com/mhdawson) - **Michael Dawson** <michael_dawson@ca.ibm.com> +* [micnic](https://github.com/micnic) - **Nicu Micleușanu** <micnic90@gmail.com> +* [mikeal](https://github.com/mikeal) - **Mikeal Rogers** <mikeal.rogers@gmail.com> +* [monsanto](https://github.com/monsanto) - **Christopher Monsanto** <chris@monsan.to> +* [ofrobots](https://github.com/ofrobots) - **Ali Ijaz Sheikh** <ofrobots@google.com> +* [Olegas](https://github.com/Olegas) - **Oleg Elifantiev** <oleg@elifantiev.ru> +* [petkaantonov](https://github.com/petkaantonov) - **Petka Antonov** <petka_antonov@hotmail.com> +* [qard](https://github.com/qard) - **Stephen Belanger** <admin@stephenbelanger.com> +* [rlidwka](https://github.com/rlidwka) - **Alex Kocharin** <alex@kocharin.ru> +* [robertkowalski](https://github.com/robertkowalski) - **Robert Kowalski** <rok@kowalski.gd> +* [romankl](https://github.com/romankl) - **Roman Klauke** <romaaan.git@gmail.com> +* [saghul](https://github.com/saghul) - **Saúl Ibarra Corretgé** <saghul@gmail.com> +* [sam-github](https://github.com/sam-github) - **Sam Roberts** <vieuxtech@gmail.com> +* [seishun](https://github.com/seishun) - **Nikolai Vavilov** <vvnicholas@gmail.com> +* [silverwind](https://github.com/silverwind) - **Roman Reiss** <me@silverwind.io> +* [srl295](https://github.com/srl295) - **Steven R Loomis** <srloomis@us.ibm.com> +* [targos](https://github.com/targos) - **Michaël Zasso** <mic.besace@gmail.com> +* [tellnes](https://github.com/tellnes) - **Christian Tellnes** <christian@tellnes.no> +* [thealphanerd](http://github.com/thealphanerd) - **Myles Borins** <myles.borins@gmail.com> +* [thefourtheye](https://github.com/thefourtheye) - **Sakthipriyan Vairamani** <thechargingvolcano@gmail.com> +* [thlorenz](https://github.com/thlorenz) - **Thorsten Lorenz** <thlorenz@gmx.de> +* [Trott](https://github.com/Trott) - **Rich Trott** <rtrott@gmail.com> +* [tunniclm](https://github.com/tunniclm) - **Mike Tunnicliffe** <m.j.tunnicliffe@gmail.com> +* [vkurchatkin](https://github.com/vkurchatkin) - **Vladimir Kurchatkin** <vladimir.kurchatkin@gmail.com> +* [yosuke-furukawa](https://github.com/yosuke-furukawa) - **Yosuke Furukawa** <yosuke.furukawa@gmail.com> + +Collaborators & TSC members follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in +maintaining the Node.js project. + +### Release Team + +Releases of Node.js and io.js will be signed with one of the following GPG keys: + +* **Chris Dickinson** <christopher.s.dickinson@gmail.com> `9554F04D7259F04124DE6B476D5A82AC7E37093B` +* **Colin Ihrig** <cjihrig@gmail.com> `94AE36675C464D64BAFA68DD7434390BDBE9B9C5` +* **Sam Roberts** <octetcloud@keybase.io> `0034A06D9D9B0064CE8ADF6BF1747F4AD2306D93` +* **Jeremiah Senkpiel** <fishrock@keybase.io> `FD3A5288F042B6850C66B31F09FE44734EB7990E` +* **James M Snell** <jasnell@keybase.io> `71DCFD284A79C3B38668286BC97EC7A07EDE3FC1` +* **Rod Vagg** <rod@vagg.org> `DD8F2338BAE7501E3DD5AC78C273792F7D83545D` + +The full set of trusted release keys can be imported by running: -```sh -vcbuild full-icu ``` +gpg --keyserver pool.sks-keyservers.net --recv-keys 9554F04D7259F04124DE6B476D5A82AC7E37093B +gpg --keyserver pool.sks-keyservers.net --recv-keys 94AE36675C464D64BAFA68DD7434390BDBE9B9C5 +gpg --keyserver pool.sks-keyservers.net --recv-keys 0034A06D9D9B0064CE8ADF6BF1747F4AD2306D93 +gpg --keyserver pool.sks-keyservers.net --recv-keys FD3A5288F042B6850C66B31F09FE44734EB7990E +gpg --keyserver pool.sks-keyservers.net --recv-keys 71DCFD284A79C3B38668286BC97EC7A07EDE3FC1 +gpg --keyserver pool.sks-keyservers.net --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D +``` + +See the section above on [Verifying Binaries](#verifying-binaries) for +details on what to do with these keys to verify that a downloaded file is official. + +Previous releases of Node.js have been signed with one of the following GPG +keys: -Resources for Newcomers ---- - - [The Wiki](https://github.com/joyent/node/wiki) - - [nodejs.org](http://nodejs.org/) - - [how to install node.js and npm (node package manager)](http://www.joyent.com/blog/installing-node-and-npm/) - - [list of modules](https://github.com/joyent/node/wiki/modules) - - [searching the npm registry](http://npmjs.org/) - - [list of companies and projects using node](https://github.com/joyent/node/wiki/Projects,-Applications,-and-Companies-Using-Node) - - [node.js mailing list](http://groups.google.com/group/nodejs) - - irc chatroom, [#node.js on freenode.net](http://webchat.freenode.net?channels=node.js&uio=d4) - - [community](https://github.com/joyent/node/wiki/Community) - - [contributing](https://github.com/joyent/node/wiki/Contributing) - - [big list of all the helpful wiki pages](https://github.com/joyent/node/wiki/_pages) +* Julien Gilli <jgilli@fastmail.fm> `114F43EE0176B71C7BC219DD50A3051F888C628D` +* Timothy J Fontaine <tjfontaine@gmail.com> `7937DFD2AB06298B2293C3187D33FF9D0246406D` +* Isaac Z. Schlueter <i@izs.me> `93C7E9E91B49E432C2F75674B0A78B0A6C481CF6`