1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: clarified & split up contribution docs

Browse Source 
- clarified the role of "collaborators"
- split out a governance doc
- split out a collaborator guide
- cleaned up the contributing doc
- cleaned up the readme & added collaborators list

PR-URL: https://github.com/iojs/io.js/pull/233
Reviewed-By: Chris Dickinson <christopher.s.dickinson@gmail.com>
Reviewed-By: Mikeal Rogers <mikeal.rogers@gmail.com>

(Note: no explicit "LGTM" from Mikeal)

Discussed at TC meeting 2015-01-07, agreed to push further
amendments to governance to future PRs.
This commit is contained in:
Rod Vagg 2015-01-02 22:52:50 +11:00
parent 913addbff5
commit c52e43d97c
4 changed files with 533 additions and 436 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
COLLABORATOR_GUIDE.md Normal file
View File

@ -0,0 +1,214 @@
# io.js Collaborator Guide
**Contents**
* Issues and Pull Requests
* Accepting Modifications
- Involving the TC
* Landing Pull Requests
- Technical HOWTO
This document contains information for Collaborators of the io.js
project regarding maintaining the code, documentation and issues.
Collaborators should be familiar with the guidelines for new
contributors in [CONTRIBUTING.md](./CONTRIBUTING.md) and also
understand the project governance model as outlined in
[GOVERNANCE.md](./GOVERNANCE.md).
## Issues and Pull Requests
Courtesy should always be shown to individuals submitting issues and
pull requests to the io.js project.
Collaborators should feel free to take full responsibility for
managing issues and pull requests they feel qualified to handle, as
long as this is done while being mindful of these guidelines, the
opinions of other Collaborators and guidance of the TC.
Collaborators may **close** any issue or pull request they believe is
not relevant for the future of the io.js project. Where this is
unclear, the issue should be left open for several days to allow for
additional discussion. Where this does not yield input from io.js
Collaborators or additional evidence that the issue has relevance, the
issue may be closed. Remember that issues can always be re-opened if
necessary.
## Accepting Modifications
All modifications to the the io.js code and documentation should be
performed via GitHub pull requests, including modifications by
Collaborators and TC members.
All pull requests must be reviewed and accepted by a Collaborator with
sufficient expertise who is able to take full responsibility for the
change. In the case of pull requests proposed by an existing
Collaborator, an additional Collaborator is required for sign-off.
In some cases, it may be necessary to summon a qualified Collaborator
to a pull request for review by @-mention.
If you are unsure about the modification and are not prepared to take
full responsibility for the change, defer to another Collaborator.
Before landing pull requests, sufficient time should be left for input
from other Collaborators. Leave at least 48 hours during the week and
72 hours over weekends to account for international time differences
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.
Where 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
TC for resolution (see below).
All bugfixes require a test case which demonstrates the defect. The
test should *fail* before the change, and *pass* after the change.
### Involving the TC
Collaborators may opt to elevate pull requests or issues to the TC for
discussion by assigning the ***tc-agenda*** tag. This should be done
where a pull request:
- has a significant impact on the codebase,
- is inherently controversial; or
- has failed to reach consensus amongst the Collaborators who are
actively participating in the discussion.
The TC should serve as the final arbiter where required.
## Landing Pull Requests
Always modify the original commit message to include additional meta
information regarding the change process:
- A `Reviewed-By: Name <email>` line for yourself and any
other Collaborators who have reviewed the change.
- 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 lead up to that change.
- A `Fixes: X` line, where _X_ is either includes the full GitHub URL
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.
See the commit log for examples such as
[this one](https://github.com/iojs/io.js/commit/b636ba8186) if unsure
exactly how to format your commit messages.
Additionally:
- Double check PR's to make sure the person's _full name_ and email
address are correct before merging.
- Except when updating dependencies, all commits should be self
contained. Meaning, every commit should pass all tests. This makes
it much easier when bisecting to find a breaking change.
### Technical HOWTO
_Optional:_ ensure that you are not in a borked `am`/`rebase` state
```text
$ git am --abort
$ git rebase --abort
```
Checkout proper target branch
```text
$ git checkout v1.x
```
Update the tree
```text
$ git fetch origin
$ git merge --ff-only origin/v1.x
```
Apply external patches
```text
$ curl https://github.com/iojs/io.js/pull/xxx.patch | git am --whitespace=fix
```
Check and re-review the changes
```text
$ git diff origin/v1.x
```
Check number of commits and commit messages
```text
$ git log origin/v1.x...v1.x
```
If there are multiple commits that relate to the same feature or
one with a feature and separate with a test for that feature -
you'll need to squash them (or strictly speaking `fixup`).
```text
$ git rebase -i origin/v1.x
```
This will open a screen like this (in the default shell editor):
```text
pick 6928fc1 crypto: add feature A
pick 8120c4c add test for feature A
pick 51759dc feature B
pick 7d6f433 test for feature B
# Rebase f9456a2..7d6f433 onto f9456a2
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
Replace a couple of `pick`s with `fixup` to squash them into a
previous commit:
```text
pick 6928fc1 crypto: add feature A
fixup 8120c4c add test for feature A
pick 51759dc feature B
fixup 7d6f433 test for feature B
```
Replace `pick` with `reword` to change the commit message:
```text
reword 6928fc1 crypto: add feature A
fixup 8120c4c add test for feature A
reword 51759dc feature B
fixup 7d6f433 test for feature B
```
Save the file and close the editor, you'll be asked to enter new
commit message for that commit, and everything else should go
smoothly. Note that this is a good moment to fix incorrect commit
logs, ensure that they are properly formatted, and add `Reviewed-By`
line.
Time to push it:
```text
$ git push origin v1.x
```

373
CONTRIBUTING.md
View File

@ -1,77 +1,87 @@
# CONTRIBUTING
# Contributing to io.js
## ISSUE CONTRIBUTIONS
## Issue Contributions
When opening new issues or commenting on existing issues on this repository
please make sure discussions are related to concrete technical issues with the
`iojs` software.
io.js software.
Discussion of non-technical topics including subjects like intellectual
property, trademark and high level project questions should move to the
[node-forward discussion repository][] instead.
[node-forward discussions repository](https://github.com/node-forward/discussions)
instead.
## CODE CONTRIBUTIONS
## Code Contributions
The io.js project welcomes new contributors. This document will guide you
through the process.
The io.js project has an open governance model and welcomes new contributors.
Individuals making significant and valuable contributions are made
_Collaborators_ and given commit-access to the project. See the
[GOVERNANCE.md](./GOVERNANCE.md) document for more information about how this
works.
This document will guide you through the contribution process.
### FORK
### Step 1: Fork
Fork the project [on GitHub](https://github.com/iojs/io.js) and check out
your copy.
Fork the project [on GitHub](https://github.com/iojs/io.js) and check out your
copy locally.
```sh
```text
$ git clone git@github.com:username/io.js.git
$ cd io.js
$ git remote add upstream git://github.com/iojs/io.js.git
```
#### Which branch?
Now decide if you want your feature or bug fix to go into the master branch
or the stable branch. As a rule of thumb, bug fixes go into the stable branch
while new features go into the master branch.
The stable branch is effectively frozen; patches that change the io.js
API/ABI or affect the run-time behavior of applications get rejected.
API/ABI or affect the run-time behavior of applications get rejected. The
current stable branch is set as the default branch on GitHub.
#### Respect the stability index
The rules for the master branch are less strict; consult the
[stability index page][] for details.
[stability index](./doc/api/documentation.markdown#stability-index) for details.
In a nutshell, modules are at varying levels of API stability. Bug fixes are
always welcome but API or behavioral changes to modules at stability level 3
always welcome but API or behavioral changes to modules at stability level 3
and up are off-limits.
io.js has several bundled dependencies in the deps/ and the tools/
#### Dependencies
io.js has several bundled dependencies in the *deps/* and the *tools/*
directories that are not part of the project proper. Any changes to files
in those directories or its subdirectories should be sent to their respective
projects. Do not send your patch to us, we cannot accept it.
In case of doubt, open an issue in the [issue tracker][], post your question
to the [node.js mailing list][] or contact one of the [project maintainers][]
on [IRC][].
Especially do so if you plan to work on something big. Nothing is more
In case of doubt, open an issue in the
[issue tracker](https://github.com/iojs/io.js/issues/) or contact one of the
[project Collaborators](https://github.com/iojs/io.js/#Current-Project-Team-Members)
([IRC](http://webchat.freenode.net/?channels=io.js) is often the best medium.)Especially do so if you plan to work on something big. Nothing is more
frustrating than seeing your hard work go to waste because your vision
does not align with that of a project maintainer.
does not align with the project team.
### BRANCH
### Step 2: Branch
Okay, so you have decided on the proper branch. Create a feature branch
and start hacking:
Create a feature branch and start hacking:
```sh
$ git checkout -b my-feature-branch -t origin/v0.12
```text
$ git checkout -b my-feature-branch -t origin/v1.x
```
(Where v0.12 is the latest stable branch as of this writing.)
(Where `v1.x` is the latest stable branch as of this writing.)
### COMMIT
### Step 3: Commit
Make sure git knows your name and email address:
```sh
```text
$ git config --global user.name "J. Random User"
$ git config --global user.email "j.random.user@example.com"
```
@ -85,14 +95,14 @@ changed and why. Follow these guidelines when writing one:
2. Keep the second line blank.
3. Wrap all other lines at 72 columns.
A good commit log looks like this:
A good commit log can look something like this:
```
subsystem: explaining the commit in one line
Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc etc.
being fixed, etc. etc.
The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
@ -107,23 +117,23 @@ Check the output of `git log --oneline files_that_you_changed` to find out
what subsystem (or subsystems) your changes touch.
### REBASE
### Step 4: Rebase
Use `git rebase` (not `git merge`) to sync your work from time to time.
```sh
```text
$ git fetch upstream
$ git rebase upstream/v0.12 # or upstream/master
$ git rebase upstream/v1.x # or upstream/master
```
### TEST
### Step 5: Test
Bug fixes and features should come with tests. Add your tests in the
Bug fixes and features **should come with tests**. Add your tests in the
test/simple/ directory. Look at other tests to see how they should be
structured (license boilerplate, common includes, etc.).
```sh
```text
$ make jslint test
```
@ -133,25 +143,25 @@ patches that fail either check.
If you are updating tests and just want to run a single test to check it, you
can use this syntax to run it exactly as the test harness would:
```
python tools/test.py -v --mode=release simple/test-stream2-transform
```text
$ python tools/test.py -v --mode=release simple/test-stream2-transform
```
You can run tests directly with node:
```
node ./test/simple/test-streams2-transform.js
```text
$ node ./test/simple/test-streams2-transform.js
```
### PUSH
### Step 6: Push
```sh
```text
$ git push origin my-feature-branch
```
Go to https://github.com/username/io.js and select your feature branch. Click
the 'Pull Request' button and fill out the form.
Go to https://github.com/yourusername/io.js and select your feature branch.
Click the 'Pull Request' button and fill out the form.
Pull requests are usually reviewed within a few days. If there are comments
to address, apply your changes in a separate commit and push that to your
@ -159,278 +169,7 @@ feature branch. Post a comment in the pull request afterwards; GitHub does
not send out notifications when you add commits.
[stability index page]: https://github.com/joyent/node/blob/master/doc/api/documentation.markdown
[issue tracker]: https://github.com/joyent/node/issues
[node.js mailing list]: http://groups.google.com/group/nodejs
[IRC]: http://webchat.freenode.net/?channels=io.js
[project maintainers]: https://github.com/joyent/node/wiki/Project-Organization
[node-forward discussion repository]: https://github.com/node-forward/discussions/issues
# Contribution Policy
Individuals making significant and valuable contributions are given
commit-access to the project. These individuals are identified by the
Technical Committee (TC) and discussed during the weekly TC meeting.
If you make a significant contribution and are not considered for
commit-access log an issue and it will be brought up in the next TC
meeting.
Internal pull-requests to solicit feedback are required for any other
non-trivial contribution but left to the discretion of the
contributor.
Pull requests may be approved by any committer with sufficient
expertise to take full responsibility for the change, according to the
"Landing Patches" protocol described below.
## Landing Patches
- All bugfixes require a test case which demonstrates the defect. The
test should *fail* before the change, and *pass* after the change.
- Trivial changes (ie, those which fix bugs or improve performance
without affecting API or causing other wide-reaching impact) may be
landed immediately after review by a committer who did not write the
code, provided that no other committers object to the change.
- If you are unsure, or if you are the author, have someone else
review the change.
- For significant changes wait a full 48 hours (72 hours if it spans a
weekend) before merging so that active contributors who are
distributed throughout the world have a chance to weigh in.
- Controversial changes and **very** significant changes should not be
merged until they have been discussed by the TC which will make any
final decisions.
- Always include the `Reviewed-by: Your Name <your-email>` in the
commit message.
- In commit messages also include `Fixes:` that either includes the
**full url** (e.g. `https://github.com/iojs/io.js/issues/...`),
and/or the hash and commit message if the commit fixes a bug in a
previous commit.
- PR's should include their full `PR-URL:` so it's easy to trace a
commit back to the conversation that lead up to that change.
- Double check PR's to make sure the person's **full name** and email
address are correct before merging.
- Except when updating dependencies, all commits should be self
contained. Meaning, every commit should pass all tests. This makes
it much easier when bisecting to find a breaking change.
### Direct instruction
(Optional) Ensure that you are not in a borked `am`/`rebase` state
```sh
git am --abort
git rebase --abort
```
Checkout proper target branch
```sh
git checkout v0.12
```
Update the tree
```sh
git fetch origin
git merge --ff-only origin/v0.12
```
Apply external patches
```sh
curl https://github.com/iojs/io.js/pull/xxx.patch | git am --whitespace=fix
```
Check and re-review the changes
```sh
git diff origin/v0.12
```
Check number of commits and commit messages
```sh
git log origin/v0.12...v0.12
```
If there are multiple commits that relate to the same feature or
one with a feature and separate with a test for that feature -
you'll need to squash them (or strictly speaking `fixup`).
```sh
git rebase -i origin/v0.12
```
This will open a screen like this (in the default shell editor):
```sh
pick 6928fc1 crypto: add feature A
pick 8120c4c add test for feature A
pick 51759dc feature B
pick 7d6f433 test for feature B
# Rebase f9456a2..7d6f433 onto f9456a2
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
```
Replace a couple of `pick`s with `fixup` to squash them into a previous commit:
```sh
pick 6928fc1 crypto: add feature A
fixup 8120c4c add test for feature A
pick 51759dc feature B
fixup 7d6f433 test for feature B
```
Replace `pick` with `reword` to change the commit message:
```sh
reword 6928fc1 crypto: add feature A
fixup 8120c4c add test for feature A
reword 51759dc feature B
fixup 7d6f433 test for feature B
```
Save the file and close the editor, you'll be asked to enter new commit message
for that commit, and everything else should go smoothly. Note that this is a
good moment to fix incorrect commit logs, ensure that they are properly
formatted, and add `Reviewed-By` line.
Time to push it:
```sh
git push origin v0.12
```
# Governance
This repository is jointly governed by a technical committee, commonly
referred to as the "TC."
The TC has final authority over this project including:
* Technical direction
* Project governance and process (including this policy)
* Contribution policy
* GitHub repository hosting
* Conduct guidelines
## Membership
Initial membership invitations to the TC were given to individuals who
had been active contributors to io.js, and who have significant
experience with the management of the io.js project. Membership is
expected to evolve over time according to the needs of the project.
Current membership is:
```
Ben Noordhuis (@bnoordhuis)
Bert Belder (@piscisaureus)
Fedor Indutny (@indutny)
Isaac Z. Schlueter (@isaacs)
Nathan Rajlich (@TooTallNate)
TJ Fontaine (@tjfontaine)
Trevor Norris (@trevnorris)
```
TC seats are not time-limited. There is no fixed size of the TC.
However, the expected target is between 6 and 12, to ensure adequate
coverage of important areas of expertise, balanced with the ability to
make decisions efficiently.
There is no specific set of requirements or qualifications for TC
membership beyond these rules.
The TC may add contributors to the TC by unanimous consensus.
A TC member may be removed from the TC by voluntary resignation, or by
unanimous consensus of all other TC members.
Changes to TC membership should be posted in the agenda, and may be
suggested as any other agenda item (see "TC Meetings" below).
If an addition or removal is proposed during a meeting, and the full
TC is not in attendance to participate, then the addition or removal
is added to the agenda for the subsequent meeting. This is to ensure
that all members are given the opportunity to participate in all
membership decisions. If a TC member is unable to attend a meeting
where a planned membership decision is being made, then their consent
is assumed.
No more than 1/3 of the TC members may be affiliated with the same
employer. If removal or resignation of a TC member, or a change of
employment by a TC member, creates a situation where more than 1/3 of
the TC membership shares an employer, then the situation must be
immediately remedied by the resignation or removal of one or more TC
members affiliated with the over-represented employer(s).
## TC Meetings
The TC meets weekly on a Google hangout. The meeting is run by a
designated moderator, currently `Mikeal Rogers (@mikeal)`. Each
meeting should be published to Youtube.
Items are added to the TC agenda which are considered contentious or
are modifications of governance, contribution policy, TC membership,
or release process. The intention of the agenda is not to approve or
review all patches, that should happen continuously on GitHub (see
"Contribution Policy").
Any community member or contributor can ask that something be added to
the next meeting's agenda by logging a GitHub Issue. Any TC member or
the moderator can add the item to the agenda by a simple +1. The
moderator and the TC cannot veto or remove items.
Prior to each TC meeting the moderator will email the Agenda to the
TC. TC members can add any items they like to the agenda at the
beginning of each meeting. The moderator and the TC cannot veto or
remove items.
TC may invite persons or representatives from certain projects to
participate in a non-voting capacity. These invitees currently are:
* A representative from [build](https://github.com/node-forward/build)
chosen by that project.
The moderator is responsible for summarizing the discussion of each
agenda item and send it as a pull request after the meeting.
## Consensus Seeking Process
The TC follows a [Consensus
Seeking](http://en.wikipedia.org/wiki/Consensus-seeking_decision-making)
decision making model.
When an agenda item has appeared to reach a consensus the moderator
will ask "Does anyone object?" as a final call for dissent from the
consensus.
If an agenda item cannot reach a consensus a TC member can call for
either a closing vote or a vote to table the issue to the next
meeting. The call for a vote must be seconded by a majority of the TC
or else the discussion will continue. Simple majority wins.
Note that changes to TC membership require unanimous consensus. See
"Membership" above.
## Caine's requirements
## Caine's Requirements
Hello!

146
GOVERNANCE.md Normal file
View File

@ -0,0 +1,146 @@
# io.js Project Governance
## Technical Committee
The io.js project is jointly governed by a Technical Committee (TC)
which is responsible for high-level guidance of the project.
The TC has final authority over this project including:
* Technical direction
* Project governance and process (including this policy)
* Contribution policy
* GitHub repository hosting
* Conduct guidelines
* Maintaining the list of additional Collaborators
Initial membership invitations to the TC were given to individuals who
had been active contributors to io.js, and who have significant
experience with the management of the io.js project. Membership is
expected to evolve over time according to the needs of the project.
For the current list of TC members, see the project
[README.md](./#current-project-team-members).
## Collaborators
The [iojs/io.js](https://github.com/iojs/io.js) GitHub repository is
maintained by the TC and additional Collaborators who are added by the
TC on an ongoing basis.
Individuals making significant and valuable contributions are made
Collaborators and given commit-access to the project. These
individuals are identified by the TC and their addition as
Collaborators is discussed during the weekly TC meeting.
_Note:_ If you make a significant contribution and are not considered
for commit-access log an issue or contact a TC member directly and it
will be brought up in the next TC meeting.
Modifications of the contents of the iojs/io.js repository are made on
a collaborative basis. Anybody with a GitHub account may propose a
modification via pull request and it will be considered by the project
Collaborators. All pull requests must be reviewed and accepted by a
Collaborator with sufficient expertise who is able to take full
responsibility for the change. In the case of pull requests proposed
by an existing Collaborator, an additional Collaborator is required
for sign-off. Consensus should be sought if additional Collaborators
participate and there is disagreement around a particular
modification. See _Consensus Seeking Process_ below for further detail
on the consensus model used for governance.
Collaborators may opt to elevate significant or controversial
modifications, or modifications that have not found consensus to the
TC for discussion by assigning the ***tc-agenda*** tag to a pull
request or issue. The TC should serve as the final arbiter where
required.
For the current list of Collaborators, see the project
[README.md](./#current-project-team-members).
A guide for Collaborators is maintained in
[COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md).
## TC Membership
TC seats are not time-limited. There is no fixed size of the TC.
However, the expected target is between 6 and 12, to ensure adequate
coverage of important areas of expertise, balanced with the ability to
make decisions efficiently.
There is no specific set of requirements or qualifications for TC
membership beyond these rules.
The TC may add additional members to the TC by unanimous consensus.
A TC member may be removed from the TC by voluntary resignation, or by
unanimous consensus of all other TC members.
Changes to TC membership should be posted in the agenda, and may be
suggested as any other agenda item (see "TC Meetings" below).
If an addition or removal is proposed during a meeting, and the full
TC is not in attendance to participate, then the addition or removal
is added to the agenda for the subsequent meeting. This is to ensure
that all members are given the opportunity to participate in all
membership decisions. If a TC member is unable to attend a meeting
where a planned membership decision is being made, then their consent
is assumed.
No more than 1/3 of the TC members may be affiliated with the same
employer. If removal or resignation of a TC member, or a change of
employment by a TC member, creates a situation where more than 1/3 of
the TC membership shares an employer, then the situation must be
immediately remedied by the resignation or removal of one or more TC
members affiliated with the over-represented employer(s).
## TC Meetings
The TC meets weekly on a Google Hangout On Air. The meeting is run by
a designated moderator approved by the TC. Each meeting should be
published to YouTube.
Items are added to the TC agenda which are considered contentious or
are modifications of governance, contribution policy, TC membership,
or release process.
The intention of the agenda is not to approve or review all patches,
that should happen continuously on GitHub and be handled by the larger
group of Collaborators.
Any community member or contributor can ask that something be added to
the next meeting's agenda by logging a GitHub Issue. Any Collaborator,
TC member or the moderator can add the item to the agenda by adding
the ***tc-agenda*** tag to the issue.
Prior to each TC meeting the moderator will share the Agenda with
members of the TC. TC members can add any items they like to the
agenda at the beginning of each meeting. The moderator and the TC
cannot veto or remove items.
The TC may invite persons or representatives from certain projects to
participate in a non-voting capacity. These invitees currently are:
* A representative from [build](https://github.com/node-forward/build)
chosen by that project.
The moderator is responsible for summarizing the discussion of each
agenda item and send it as a pull request after the meeting.
## Consensus Seeking Process
The TC follows a
[Consensus Seeking](http://en.wikipedia.org/wiki/Consensus-seeking_decision-making)
decision making model.
When an agenda item has appeared to reach a consensus the moderator
will ask "Does anyone object?" as a final call for dissent from the
consensus.
If an agenda item cannot reach a consensus a TC member can call for
either a closing vote or a vote to table the issue to the next
meeting. The call for a vote must be seconded by a majority of the TC
or else the discussion will continue. Simple majority wins.
Note that changes to TC membership require unanimous consensus. See
"TC Membership" above.

236
README.md
View File

@ -4,21 +4,24 @@ io.js
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](./CONTRIBUTING.md#governance).
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?
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.)
### To build:
## To build:
Prerequisites (Unix only):
### Unix / Macintosh
Prerequisites:
* `gcc` and `g++` 4.8 or newer, or
* `clang` and `clang++` 3.3 or newer
@ -26,77 +29,59 @@ Prerequisites (Unix only):
* GNU Make 3.81 or newer
* libexecinfo (FreeBSD and OpenBSD only)
Unix/Macintosh:
```sh
./configure
make
make install
```text
$ ./configure
$ make
$ make install
```
If your python binary is in a non-standard location or has a
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
$ make install
```
Prerequisites (Windows only):
To run the tests:
* Python 2.6 or 2.7
```text
$ make test
```
To build the documentation:
```text
$ make doc
```
To read the documentation:
```text
$ man doc/node.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`.
Windows:
```sh
vcbuild nosign
```text
> vcbuild nosign
```
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 run the tests:
```sh
tar xzf /path/to/node-<version>-<platform>-<arch>.tar.gz
```
Or system-wide with:
```sh
cd /usr/local && tar --strip-components 1 -xzf \
/path/to/node-<version>-<platform>-<arch>.tar.gz
```
### To run the tests:
Unix/Macintosh:
```sh
make test
```
Windows:
```sh
vcbuild test
```
### To build the documentation:
```sh
make doc
```
### To read the documentation:
```sh
man doc/node.1
```text
> vcbuild test
```
### `Intl` (ECMA-402) support:
@ -110,62 +95,62 @@ 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 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`.
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
```
#### Build with a specific ICU:
@ -175,42 +160,55 @@ 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
# 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
```
Unix/Macintosh: from a local ICU tarball
Windows
```sh
./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
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
```
Unix/Macintosh: from a tarball URL
## Resources for Newcomers
```sh
./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
```
* [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)
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
vcbuild full-icu
```
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, [#io.js on freenode.net](http://webchat.freenode.net?channels=io.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)
## 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)) &lt;i@izs.me&gt; (Technical Committee)
* **Ben Noordhuis** ([@bnoordhuis](https://github.com/bnoordhuis)) &lt;info@bnoordhuis.nl&gt; (Technical Committee)
* **Bert Belder** ([@piscisaureus](https://github.com/piscisaureus)) &lt;bertbelder@gmail.com&gt; (Technical Committee)
* **Fedor Indutny** ([@indutny](https://github.com/indutny)) &lt;fedor.indutny@gmail.com&gt; (Technical Committee)
* **Trevor Norris** ([@trevnorris](https://github.com/trevnorris)) &lt;trev.norris@gmail.com&gt; (Technical Committee)
* **Chris Dickinson** ([@chrisdickinson](https://github.com/chrisdickinson)) &lt;christopher.s.dickinson@gmail.com&gt; (Technical Committee)
* **Colin Ihrig** ([@cjihrig](https://github.com/cjihrig)) &lt;cjihrig@gmail.com&gt; (Technical Committee)
* **Mikeal Rogers** ([@mikeal](https://github.com/mikeal)) &lt;mikeal.rogers@gmail.com&gt;
* **Rod Vagg** ([@rvagg](https://github.com/rvagg)) &lt;rod@vagg.org&gt;
Collaborators follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in
maintaining the io.js project.