mirror of https://github.com/lukechilds/node.git
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.v1.8.0-commit
Rod Vagg
10 years ago
4 changed files with 523 additions and 426 deletions
@ -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 |
||||
|
``` |
||||
@ -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. |
||||
Loading…
Reference in new issue