From 5d829a63ab468a43b4084e15523ddd7b43f3473b 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/3965 Reviewed-By: Alexis Campailla Reviewed-By: Johan Bergström --- README.md | 332 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 282 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 12fd05aa5ff03d..bbcf6014a3587a 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,306 @@ -Evented I/O for V8 javascript. [![Build Status](https://secure.travis-ci.org/joyent/node.png)](http://travis-ci.org/joyent/node) -=== +Node.js +======= -### To build: +[![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) -Prerequisites (Unix only): +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). - * GCC 4.2 or newer - * Python 2.6 or 2.7 - * GNU Make 3.81 or newer - * libexecinfo (FreeBSD and OpenBSD only) +If you need help using or installing Node.js, please use the +[nodejs/help](https://github.com/nodejs/help) issue tracker. -Unix/Macintosh: +## Release Types - ./configure - make - make install +The Node.js project maintains multiple types of releases: -If your python binary is in a non-standard location or has a +* **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: + +``` +$ grep node-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - +``` + +_(Where "node-vx.y.z.tar.gz" is the name of the file you have +downloaded)_ + +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. + +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: + +``` +$ 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 + +### 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: - export PYTHON=/path/to/python - $PYTHON ./configure - make - make install +```text +$ export PYTHON=/path/to/python +$ $PYTHON ./configure +$ make +$ [sudo] make install +``` + +To run the tests: + +```text +$ make test +``` + +To build the documentation: + +```text +$ make doc +``` + +To read the documentation: + +```text +$ man doc/node.1 +``` + +To test if Node.js was built correctly: + +``` +$ node -e "console.log('Hello from node.js ' + process.version)" +``` + +### Windows + +Prerequisites: + +* [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 +``` + +To run the tests: + +```text +> vcbuild test +``` + +To test if Node.js was built correctly: + +``` +$ node -e "console.log('Hello from node.js ' + process.version)" +``` + +### Android / Android based devices, aka. Firefox OS + +Be sure you have downloaded and extracted [Android NDK] +(https://developer.android.com/tools/sdk/ndk/index.html) +before in a folder. Then run: + +``` +$ ./android-configure /path/to/your/android-ndk +$ make +``` + +## 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. -Windows: +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. - vcbuild.bat +## Current Project Team Members -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 to install to. -The tarballs are self-contained; you can extract them to a local directory -with: +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). - tar xzf /path/to/node---.tar.gz +### TSC (Technical Steering Committee) -Or system-wide with: +* [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> - cd /usr/local && tar --strip-components 1 -xzf \ - /path/to/node---.tar.gz +### Collaborators -### To run the tests: +* [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> -Unix/Macintosh: +Collaborators & TSC members follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in +maintaining the Node.js project. - make test +### Release Team -Windows: +Releases of Node.js and io.js will be signed with one of the following GPG keys: - vcbuild.bat test +* **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` -### To build the documentation: +The full set of trusted release keys can be imported by running: - make doc +``` +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 +``` -### To read the documentation: +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. - man doc/node.1 +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`