diff --git a/DEPRECATION.md b/DEPRECATION.md new file mode 100644 index 000000000..d9a265fe1 --- /dev/null +++ b/DEPRECATION.md @@ -0,0 +1,26 @@ +# Deprecation Policy + +## Stage 1 + +1. The technical committee decides to deprecate an officially supported API. +2. The function is changed to the `util.deprecate` function with a message that indicates the intent for removal and a +suggested replacement API to use, if there is one. +3. The API documentation is updated to reflect that the API functionality will be removed in the future. +4. The changed API is released with the minor version being incremented. +5. An issue is filed to delete the deprecated API + + +## Stage 2 + +1. During the next major release since the release of the deprecated API, the API should be deleted. The +related issue from step 5 stage 1 is closed. +2. The API documentation is updated to reflect that the API functionality has been deleted. +3. Release notes are created to guide developers on the breaking change and how to upgrade. +4. The major version is incremented and a release is issued +5. An issue is filed to remove the note from the API documentation + + +## Stage 3 + +1. Remove the note from the API documentation and close the issue from step 5 stage 2. +2. The documentation change can go out with any future release diff --git a/README.md b/README.md index 509fd8bb2..02c3112fb 100644 --- a/README.md +++ b/README.md @@ -1,303 +1,18 @@ -io.js +Node.js Foundation - Node.js ===== -[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/iojs/io.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) +This repository is the working repository for the proposed convergence of the +http://github.com/iojs/io.js and http://github.com/joyent/node projects under +the Node.js Foundation. -This repository began as a GitHub fork of -[joyent/node](https://github.com/joyent/node). +Contributions, releases, and contributorship are under the proposed +Governance and Developer Policy for the soon-to-be-launched Node.js +Foundation: -io.js contributions, releases, and contributorship are under an -[open governance model](./GOVERNANCE.md). -We intend to land, with increasing regularity, releases which are -compatible with the npm ecosystem that has been built to date for -Node.js. +* https://github.com/joyent/nodejs-advisory-board/tree/master/governance-proposal +* http://github.com/jasnell/dev-policy -## Is it io.js or IO.js or iojs or IOjs or iOjS? +This project is operating with the oversight of the joint Node.js and io.js +core technical teams. -The official name is **io.js**, which should never be capitalized, -especially not at the start of a sentence, unless it is being -displayed in a location that is customarily all-caps (such as -the title of man pages). - -## Download - -Binaries, installers, and source tarballs are available at -. - -**Releases** are available at , listed under -their version string. The symlink -will point to the latest release directory. - -**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 latest version. - -### Verifying Binaries - -Release 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 iojs-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - -``` - -_(Where "iojs-vx.y.z.tar.gz" is the name of the file you have -downloaded)_ - -Additionally, 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. Use a command such as this to -import the keys: - -``` -$ gpg --keyserver pool.sks-keyservers.net \ - --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D -``` - -_(Include each of the key fingerprints at the end of this command.)_ - -You can then use `gpg --verify SHASUMS256.txt.asc` to verify that the -file has been signed by an authorized member of the io.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` and `g++` 4.8 or newer, or -* `clang` and `clang++` 3.4 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: - -```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/iojs.1 -``` - -### Windows - -Prerequisites: - -* [Python 2.6 or 2.7](https://www.python.org/downloads/) -* 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 -``` - -### 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 -``` - -### `Intl` (ECMA-402) support: - -[Intl](https://github.com/joyent/node/wiki/Intl) support is not -enabled by default. - -#### "small" (English only) support - -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: - -```text -$ ./configure --with-intl=small-icu --download=all -``` - -Windows: - -```text -> vcbuild small-icu download-all -``` - -The `small-icu` mode builds with English-only data. You can add full -data at runtime. - -*Note:* more docs are on -[the joyent/node wiki](https://github.com/joyent/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`. - -Unix / Macintosh: - -```text -$ ./configure --with-intl=full-icu --download=all -``` - -Windows: - -```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. - -Unix / Macintosh: - -```text -$ ./configure --with-intl=none -``` - -Windows: - -```text -> vcbuild intl-none -``` - -#### Use existing installed ICU (Unix / Macintosh only): - -```text -$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu -``` - -#### Build with a specific ICU: - -You can find other ICU releases at -[the ICU homepage](http://icu-project.org/download). -Download the file named something like `icu4c-**##.#**-src.tgz` (or -`.zip`). - -Unix / Macintosh - -```text -# from an already-unpacked ICU: -$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu - -# from a local ICU tarball -$ ./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 -``` - -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/...`) - -```text -> vcbuild full-icu -``` - -## Resources for Newcomers - -* [CONTRIBUTING.md](./CONTRIBUTING.md) -* [GOVERNANCE.md](./GOVERNANCE.md) -* IRC: - [#io.js on Freenode.net](http://webchat.freenode.net?channels=io.js&uio=d4) -* [iojs/io.js on Gitter](https://gitter.im/iojs/io.js) - - - -## Current Project Team Members - -The io.js project team comprises a group of core collaborators and a sub-group -that forms the _Technical Committee_ (TC) which governs the project. For more -information about the governance of the io.js project, see -[GOVERNANCE.md](./GOVERNANCE.md). - -* **Isaac Z. Schlueter** ([@isaacs](https://github.com/isaacs)) <i@izs.me> (Technical Committee) -* **Ben Noordhuis** ([@bnoordhuis](https://github.com/bnoordhuis)) <info@bnoordhuis.nl> (Technical Committee) -* **Bert Belder** ([@piscisaureus](https://github.com/piscisaureus)) <bertbelder@gmail.com> (Technical Committee) -* **Fedor Indutny** ([@indutny](https://github.com/indutny)) <fedor.indutny@gmail.com> (Technical Committee) -* **Trevor Norris** ([@trevnorris](https://github.com/trevnorris)) <trev.norris@gmail.com> (Technical Committee) -* **Chris Dickinson** ([@chrisdickinson](https://github.com/chrisdickinson)) <christopher.s.dickinson@gmail.com> (Technical Committee) - - Release GPG key: 9554F04D7259F04124DE6B476D5A82AC7E37093B -* **Colin Ihrig** ([@cjihrig](https://github.com/cjihrig)) <cjihrig@gmail.com> -* **Mikeal Rogers** ([@mikeal](https://github.com/mikeal)) <mikeal.rogers@gmail.com> -* **Rod Vagg** ([@rvagg](https://github.com/rvagg)) <rod@vagg.org> (Technical Committee) - - Release GPG key: DD8F2338BAE7501E3DD5AC78C273792F7D83545D -* **Thorsten Lorenz** ([@thlorenz](https://github.com/thlorenz)) <thlorenz@gmx.de> -* **Stephen Belanger** ([@qard](https://github.com/qard)) <admin@stephenbelanger.com> -* **Jeremiah Senkpiel** ([@fishrock123](https://github.com/fishrock123)) <fishrock123@rocketmail.com> (Technical Committee) - - Release GPG key: FD3A5288F042B6850C66B31F09FE44734EB7990E -* **Evan Lucas** ([@evanlucas](https://github.com/evanlucas)) <evanlucas@me.com> -* **Brendan Ashworth** ([@brendanashworth](https://github.com/brendanashworth)) <brendan.ashworth@me.com> -* **Vladimir Kurchatkin** ([@vkurchatkin](https://github.com/vkurchatkin)) <vladimir.kurchatkin@gmail.com> -* **Nikolai Vavilov** ([@seishun](https://github.com/seishun)) <vvnicholas@gmail.com> -* **Nicu Micleușanu** ([@micnic](https://github.com/micnic)) <micnic90@gmail.com> -* **Aleksey Smolenchuk** ([@lxe](https://github.com/lxe)) <lxe@lxe.co> -* **Shigeki Ohtsu** ([@shigeki](https://github.com/shigeki)) <ohtsu@iij.ad.jp> -* **Sam Roberts** ([@sam-github](https://github.com/sam-github)) <vieuxtech@gmail.com> -* **Wyatt Preul** ([@geek](https://github.com/geek)) <wpreul@gmail.com> -* **Brian White** ([@mscdex](https://github.com/mscdex)) <mscdex@mscdex.net> -* **Christian Vaagland Tellnes** ([@tellnes](https://github.com/tellnes)) <christian@tellnes.com> -* **Robert Kowalski** ([@robertkowalski](https://github.com/robertkowalski)) <rok@kowalski.gd> -* **Julian Duque** ([@julianduque](https://github.com/julianduque)) <julianduquej@gmail.com> -* **Johan Bergström** ([@jbergstroem](https://github.com/jbergstroem)) <bugs@bergstroem.nu> -* **Roman Reiss** ([@silverwind](https://github.com/silverwind)) <me@silverwind.io> -* **Petka Antonov** ([@petkaantonov](https://github.com/petkaantonov)) <petka_antonov@hotmail.com> -* **Yosuke Furukawa** ([@yosuke-furukawa](https://github.com/yosuke-furukawa)) <yosuke.furukawa@gmail.com> - -Collaborators follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in -maintaining the io.js project. +Note: The original io.js README.md is temporarily renamed to iojs_README.md. diff --git a/iojs_README.md b/iojs_README.md new file mode 100644 index 000000000..ca5ab327b --- /dev/null +++ b/iojs_README.md @@ -0,0 +1,304 @@ +io.js +===== + +[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/iojs/io.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + +This repository began as a GitHub fork of +[joyent/node](https://github.com/joyent/node). + +io.js contributions, releases, and contributorship are under an +[open governance model](./GOVERNANCE.md). +We intend to land, with increasing regularity, releases which are +compatible with the npm ecosystem that has been built to date for +Node.js. + +## Is it io.js or IO.js or iojs or IOjs or iOjS? + +The official name is **io.js**, which should never be capitalized, +especially not at the start of a sentence, unless it is being +displayed in a location that is customarily all-caps (such as +the title of man pages). + +## Download + +Binaries, installers, and source tarballs are available at +. + +**Releases** are available at , listed under +their version string. The symlink +will point to the latest release directory. + +**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 the +latest version. + +### Verifying Binaries + +Release 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 iojs-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c - +``` + +_(Where "iojs-vx.y.z.tar.gz" is the name of the file you have +downloaded)_ + +Additionally, 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. Use a command such as this to +import the keys: + +``` +$ gpg --keyserver pool.sks-keyservers.net \ + --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D +``` + +_(Include each of the key fingerprints at the end of this command.)_ + +You can then use `gpg --verify SHASUMS256.txt.asc` to verify that the +file has been signed by an authorized member of the io.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` and `g++` 4.8 or newer, or +* `clang` and `clang++` 3.4 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: + +```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/iojs.1 +``` + +### Windows + +Prerequisites: + +* [Python 2.6 or 2.7](https://www.python.org/downloads/) +* 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 +``` + +### 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 +``` + +### `Intl` (ECMA-402) support: + +[Intl](https://github.com/joyent/node/wiki/Intl) support is not +enabled by default. + +#### "small" (English only) support + +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: + +```text +$ ./configure --with-intl=small-icu --download=all +``` + +Windows: + +```text +> vcbuild small-icu download-all +``` + +The `small-icu` mode builds with English-only data. You can add full +data at runtime. + +*Note:* more docs are on +[the joyent/node wiki](https://github.com/joyent/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`. + +Unix / Macintosh: + +```text +$ ./configure --with-intl=full-icu --download=all +``` + +Windows: + +```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. + +Unix / Macintosh: + +```text +$ ./configure --with-intl=none +``` + +Windows: + +```text +> vcbuild intl-none +``` + +#### Use existing installed ICU (Unix / Macintosh only): + +```text +$ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu +``` + +#### Build with a specific ICU: + +You can find other ICU releases at +[the ICU homepage](http://icu-project.org/download). +Download the file named something like `icu4c-**##.#**-src.tgz` (or +`.zip`). + +Unix / Macintosh + +```text +# from an already-unpacked ICU: +$ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu + +# from a local ICU tarball +$ ./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 +``` + +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/...`) + +```text +> vcbuild full-icu +``` + +## Resources for Newcomers + +* [CONTRIBUTING.md](./CONTRIBUTING.md) +* [GOVERNANCE.md](./GOVERNANCE.md) +* IRC: + [#io.js on Freenode.net](http://webchat.freenode.net?channels=io.js&uio=d4) +* [iojs/io.js on Gitter](https://gitter.im/iojs/io.js) + + + +## Current Project Team Members + +The io.js project team comprises a group of core collaborators and a sub-group +that forms the _Technical Committee_ (TC) which governs the project. For more +information about the governance of the io.js project, see +[GOVERNANCE.md](./GOVERNANCE.md). + +* **Isaac Z. Schlueter** ([@isaacs](https://github.com/isaacs)) <i@izs.me> (Technical Committee) +* **Ben Noordhuis** ([@bnoordhuis](https://github.com/bnoordhuis)) <info@bnoordhuis.nl> (Technical Committee) +* **Bert Belder** ([@piscisaureus](https://github.com/piscisaureus)) <bertbelder@gmail.com> (Technical Committee) +* **Fedor Indutny** ([@indutny](https://github.com/indutny)) <fedor.indutny@gmail.com> (Technical Committee) +* **Trevor Norris** ([@trevnorris](https://github.com/trevnorris)) <trev.norris@gmail.com> (Technical Committee) +* **Chris Dickinson** ([@chrisdickinson](https://github.com/chrisdickinson)) <christopher.s.dickinson@gmail.com> (Technical Committee) + - Release GPG key: 9554F04D7259F04124DE6B476D5A82AC7E37093B +* **Colin Ihrig** ([@cjihrig](https://github.com/cjihrig)) <cjihrig@gmail.com> +* **Mikeal Rogers** ([@mikeal](https://github.com/mikeal)) <mikeal.rogers@gmail.com> +* **Rod Vagg** ([@rvagg](https://github.com/rvagg)) <rod@vagg.org> + - Release GPG key: DD8F2338BAE7501E3DD5AC78C273792F7D83545D +* **Thorsten Lorenz** ([@thlorenz](https://github.com/thlorenz)) <thlorenz@gmx.de> +* **Stephen Belanger** ([@qard](https://github.com/qard)) <admin@stephenbelanger.com> +* **Jeremiah Senkpiel** ([@fishrock123](https://github.com/fishrock123)) <fishrock123@rocketmail.com> (Technical Committee) + - Release GPG key: FD3A5288F042B6850C66B31F09FE44734EB7990E +* **Evan Lucas** ([@evanlucas](https://github.com/evanlucas)) <evanlucas@me.com> +* **Brendan Ashworth** ([@brendanashworth](https://github.com/brendanashworth)) <brendan.ashworth@me.com> +* **Vladimir Kurchatkin** ([@vkurchatkin](https://github.com/vkurchatkin)) <vladimir.kurchatkin@gmail.com> +* **Nikolai Vavilov** ([@seishun](https://github.com/seishun)) <vvnicholas@gmail.com> +* **Nicu Micleușanu** ([@micnic](https://github.com/micnic)) <micnic90@gmail.com> +* **Aleksey Smolenchuk** ([@lxe](https://github.com/lxe)) <lxe@lxe.co> +* **Shigeki Ohtsu** ([@shigeki](https://github.com/shigeki)) <ohtsu@iij.ad.jp> +* **Sam Roberts** ([@sam-github](https://github.com/sam-github)) <vieuxtech@gmail.com> +* **Wyatt Preul** ([@geek](https://github.com/geek)) <wpreul@gmail.com> +* **Brian White** ([@mscdex](https://github.com/mscdex)) <mscdex@mscdex.net> +* **Christian Vaagland Tellnes** ([@tellnes](https://github.com/tellnes)) <christian@tellnes.com> +* **Robert Kowalski** ([@robertkowalski](https://github.com/robertkowalski)) <rok@kowalski.gd> +* **Julian Duque** ([@julianduque](https://github.com/julianduque)) <julianduquej@gmail.com> +* **Johan Bergström** ([@jbergstroem](https://github.com/jbergstroem)) <bugs@bergstroem.nu> +* **Roman Reiss** ([@silverwind](https://github.com/silverwind)) <me@silverwind.io> +* **Petka Antonov** ([@petkaantonov](https://github.com/petkaantonov)) <petka_antonov@hotmail.com> +* **Yosuke Furukawa** ([@yosuke-furukawa](https://github.com/yosuke-furukawa)) <yosuke.furukawa@gmail.com> + +Collaborators follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in +maintaining the io.js project.