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