Diffing io.js and the Node.js Foundation

[mikeal]

The foundation policy drafts are here but the sheer size and volume of documentation is a little intimidating.

In order for the io.js community to evaluate what a merger looks like we need a better way for everyone to understand what could/would change.

I'd like to use this issue to track any differences between io.js and the Node.js Foundation policies. I don't want to make any judgement calls about these differences I merely want to expose each difference so that everyone can objectively evaluate it themselves.

Summary

I'll keep this summary up to date as people find more differences and post comments.

TSC Charter

• Charter states that no more than 1/4 of the TSC can be employed by the same company. io.js currently has this at a 1/3 rule.
• Charter defines a "TSC Chairperson."
  • Chairperson holds the responsibilities that io.js' current moderator holds.
  • Chairperson represents the TSC on the foundations Board of Directors
  • Chairperson is elected by TSC using Condorcet or Single Transferable Vote
• Voting rules and consensus seeking model are identical except that a 2/3 majority is required when changing the TSC Charter and when adding/removing members of the TSC. In io.js all decisions when brought to a vote are simple majority.

Project Lifecycle

• Lifecycle Ladder
  • In io.js there are two WG states: chartered and un-chartered. Working groups begin informally and collaborate until they are mature enough to write a charter which is ratified by the TSC.
  • In the foundation, working groups are "incubating" when they are working either unchartered or completely outside the foundation. When they write a charter they are in the "Proposal" phase until accepted and then are considered "Mature" which is identical in state to io.js' "chartered" state.
  • A final state in the Lifecycle is "Core" which has no equivolent in io.js. Once a WG reaches the core state they get a TSC seat.
• Multiple "core" projects.
  • Basically, this allows for another sizable project, like express or hapi, to join the foundation and get its own TSC at the same level as the Core TSC.
• In io.js working groups are chartered by the TSC at their discretion. While it is not done being drafted the review requirements for each state change will be documented in the lifecycle.

Development Policy

• Guiding Principals is a project vision that is lacking in both io.js and node.js as formal documentation and is really only understood culturally.
• Collaborators
  • Describes the process: a new issue is created by a TSC member with recent contributors and the names can be challenged by other contributors the same way changes are reviewed to reach a consensus. This is the existing io.js policy but it is not formally document in io.js.
  • Explicitly states that TSC candidates be nominated from the pool of Collaborators. This has been the case in io.js but it is not explicitely stated.
• Accepting Modifications
  • Wide and well documented definition of "contribution." Similar if not identical to the io.js cultural definition but not formally documented yet.
  • All pull requests must be signed off by another collaborator. The io.js dev policy has an exception for "trivial changes" but in practice contributors (even long time ones) have been chastised for not getting a sign off. Note: the 48 - 72 hour rule still has an exception for "trivial changes."
  • Any PR that will bump the major version will be elevated to the tsc-agenda.
  • Exception to all processes for critical security vulnerabilities. Since the security policy responsibly discloses fixes they may need to be done outside of the regular public process.
  • "All Pull Requests that either fix bugs or introduce new functionality require at least one test case"
• master is the current branch. This differs from io.js' current policy but matches @chrisdickinson's proposed improvements to it.
• release branches (prior major releases) are owned by the LTS working group. io.js states that a future LTS WG will handle these kinds of releases but the branch ownership has not been addressed.
• Issue Tagging is formally documented. The tags and strategy match the current io.js practice which is undocumented.
• Release Branchs for LTS. This is totally new and has no equivalent in io.js at this time.
• Release Versioning requirements are defined for major, minor and patch. io.js simply states that "semver" is the policy without a greater definition.
• "Releases should not contain too many code changes and if the rate of code changes is high then it should correspond to an increase in the rate of releases." This matches io.js in practice but cadence is not explicitly documented.
• "Master must pass a full CI test run prior to release."
• Repository Reconciliation Plan
  • Obviously this has no equivalent in io.js because it addresses how io.js and node.js would be merged.
  • Versioning strategy would ensure that io.js and node.js do not have any version overlap.
  • A "Convergence Working Group" will define a more detailed proposal of how to merge the code and resources together.
• LTS -- TODO (I'm not familiar with the state of the LTS discussions Rod has been leading)
• Issue Workflow -- Still an open discussion, nothing concrete yet.
• Stability Policy
  • Mostly similar to io.js Stability Policy.
  • Much more attention paid to ABI compatibility.
  • Puts the ABI under the same semver major/minor/patch restrictions as the JS API
  • "Any Modification to the ABI, dependencies or Native abstractions that require a developer to modify code and then recompile is considered a backwards incompatible change that must result in a semver-major version increase." This Is not the current policy in io.js as it is currently documented but, in practice, the TC decided to float a small patch that broke ABI compatibility for a future major version release.
• Implicit vs. Explicit API Stability
  • This section describes and area that is not very well understood or documented in either io.js or node.js. The existing policies in both projects have been subjective.
  • Basically, they are trying to define what is internal API vs. external API.
  • There is also a lot of effort spent on defining exactly how many type guarantees the API is offering implicitely vs. explicitely because types are rarely if ever documented formally.
• Platform Stability -- In io.js we just sort of add platforms to CI and when they are green more often then not we start blocking releases on them. This section defines states the various platforms are in and what the stability guarantees are once they get a label.
• Dependency Stability
  • "Node.js will adopt new V8 releases as quickly as practically feasible. For LTS Releases, the version of V8 shipped must be fully functional with no regressions on all Primary Platforms." This is the io.js policy in practice but is not documented.
• "When new features in the JavaScript language are introduced by V8, there will be a semver-minor version increase." io.js has never had to deal with this, and I doubt it will ever come up because when v8 ads language features it's in a major release anyway.
• "With a few notable exceptions, the Node.js Core Library API is largely built around ES5 Language features. While there are currently no plans to do so, it is possible for post-ES5 JavaScript language features to be introduced into the Core Library API in the future." This is a little bolder than we've gotten so far in io.js, we've never actually exposed any ES6 usage, only used it a little internally.

Other

Trademark

Right now io.js has no trademark and as such it has no trademark policy. The foundation lawyers will be drafting a new trademark policy for node.js but it doesn't exist yet. Joyent's prior trademark policy will no longer exist.

Foundation Board of Directors

io.js is not a legal entity. Property is owned haphazardly between several individuals and a handful of companies. Such as:

• Domain name and DNS is owned by Fedor.
• Twitter is registered by Fedor but login shared with about a dozen people.
• Google Plus, Facebook, and Medium accounts by Mikeal.
• GitHub org by Colin.
• Build resources donated by various companies differing by architecture.
• Signing keys are from NodeSource (I think?)

A non-profit foundation is an actual legal entity and can own property. It is operated by the board of directors and elected executives. The board not only shares the task of administering the foundation but can, in some cases, be held legally and financially responsible for it.

In a foundation all the property is owned by the foundation (legal entity). The TSC is given autonomy to run the technical side of the project and do releases but the foundation sets the budget, administers funds, and handles all legal matters.

That means that if someone wants to sue the project they would sue the foundation, rather than Fedor (good luck he's Russian), or me, or NodeSource.

[trevordmiller]

So are io.js and Node.js going to merge? I would love to see that. I realize that io has had a lot more freedom and progression but we were just barely able to get "official" approval to use Node at my current company - slow moving, I know; Point is, the "node" name means a lot to the community and has trust and maturity behind it for managers and conservative leads; I'd love to see the innovation and contributors of io come back under the "node" umbrella to get the best of both worlds :)

[mikeal]

Ok, huge update with what I could pull out of the dev policy before I passed out :)

[mikeal]

So are io.js and Node.js going to merge?

That has not been decided. What we're trying to do here is figure out what that would actually look like and push it in a direction that is acceptable to everyone.

[rvagg]

"When new features in the JavaScript language are introduced by V8, there will be a semver-minor version increase." io.js has never had to deal with this, and I doubt it will ever come up because when v8 ads language features it's in a major release anyway.

Why is it necessarily a major release? I feel like I might have missed something about V8 bumps and major versions and was under the impression that we were only bumping major (2.0) for the next V8 upgrade because it seemed like a good chance to throw some of the semver-major changes in. But, a V8 upgrade, even introducing language features, should generally only ever be a semver-minor unless they really screwed something up. I think we've created an exception around the C++ API and Chrome isn't very likely to break JavaScript-land stuff.

[rvagg]

btw, thanks for this @mikeal, makes it so much easier to grok for those of us who are time-poor. Overall the list looks fairly manageable if this really is all there is to it.

[mikeal]

@rvagg sorry, I'll try to state that better. What I meant is, I haven't seen v8 add language features in a release that didn't break ABI from its prior stable release. The policy as stated actually says that we're only going to increase the minor on a language addition but I'm pretty sure that in practice we'll end up eating a major version bump anyway for other reasons.

[jbergstroem]

@rvagg said
this makes it so much easier to grok for those of us who are time-poor.

Agree, so I apologise in advance if below should live somewhere else.

@mikeal said
"Master must pass a full CI test run prior to release."

This needs to be improved:

• It limits when a release can be made since we're fighting longstanding test failures on some platforms. It additionally encourages hiding issues under the rug so a release can be made.
• It prohibits new platforms to be added to CI. We'd essentially avoid adding OpenBSD because it'd add 10 test failures that would in turn push a new release indefinitely.

Another small difference I've noted is that nodejs seems to prefer Reviewed-By as their first "meta" in the commit message while we prefer PR-URL. I would suggest changing the order in the document as well as stating order should follow the list (pr-url to reviewers to fixes).

Finally, I haven't seen anything about how different commits should land in different branches. For now, io.js handled it by PR'ed merge-commits but I doubt that'll scale. Labels could simplify the life of the person merging, but who decides what goes where and when?

[mikeal]

It limits when a release can be made since we're fighting longstanding test failures on some platforms. It additionally encourages hiding issues under the rug so a release can be made.

Is this still true in io.js? I was under the impression that on primary platforms all the tests pass.

It prohibits new platforms to be added to CI. We'd essentially avoid adding OpenBSD because it'd add 10 test failures that would in turn push a new release indefinitely.

The "Platform Stability" section tries to address this. Basically, you can add OpenBSD to CI, and it'll run regularly, but it won't block a release.

[jbergstroem]

Is this still true in io.js?

Yes and no. Jenkins tells us there's three failing slaves on the last run. Since some are only reproducible within a Jenkins environment it's arguably classified as heisenbugs. With language like that (even if platform stability addresses cases like new platforms) a critical bug fix release shouldn't go out even if the CI itself is to blame.

The bigger picture is great though. We're in better shape than ever and will soon be 100% green (jenkins-speak: blue) -- but I'd rather be slightly less strict than "break the rules" when we end up in that situation.

[mikeal]

@jbergstroem interesting, can you log an issue on the dev-policy repo about that.

[jasnell]

@mikeal ... heh, I just put a new PR that would update some of the dev-policy details (simplify based on feedback). It would likely reduce some of the deltas. Tomorrow I'll go through your list above in detail and see if I can call out the possible changes.

nodejs/dev-policy#59