OpenSocial Specification Definition Process

Background

OpenSocial is a community product, which isn't owned by any one company or individual, and it is important that the technical specification is driven by that community. This document outlines the steps by which that community operates to make changes to the OpenSocial specification (including the gadgets sub-component).

The basic model is to treat the specification as an open source project, and thus we can borrow many of the tenets from the Apache Software Foundation, which is well-known to help foster high-quality communities (and software):

Participation is open to anyone
Decisions are made on the public list (not behind closed doors)
All proceedings are captured in a public archive
Individuals represent themselves, not companies

The discussion forum for new contributions and archive of past discussions is located in the OpenSocial Specification List.

Process Overview

Borrowing from the IETF, the model of "(rough) consensus and running code" fits reasonably well for the OpenSocial specification community process. That is, prior to a proposal making its way into an official specification, it must gather community support for the idea as well as prove the concept through a running prototype.

To that end, the process is laid out to require positive agreement from at least 5 members of the community. In addition, if any negative "vote(s)" are cast, then a given proposal will not be included unless the negative vote(s) are rescinded.

Producing a new version of the specification is a large undertaking, requiring work by a lot of people, and thus it is not desirable to iterate too quickly. However, since OpenSocial is still evolving, it is important to enable the specification to be responsive to needs of the community. It is expected that a new version will be produced every 3 or 4 months (typically 3 months for the specification definition and prototyping and then a 1 month gap before the next version begins).

Contributions & Intellectual Property

Since participation is open to anyone, to help ensure OpenSocial remains freely implementable by all, the OpenSocial Foundation has created an intellectual property rights management structure to enable a broad range of contributions while still helping protect implementers of the spec. This means that, prior to contributing to the specification, individuals must submit the OpenSocial Foundation's Contribution Licensing Agreement. Additionally, prior to finalizing the specification, all contributors must submit the OpenSocial Foundation's Non-Assert Agreement. In the case of corporate contributions, the proper document is the OpenSocial Foundation's Corporate Contribution Licensing Agreement.

As an aside, in the interest of transparency and ease of shepherding, each form has a publicly viewable snapshot of the entries (sanitized so we're not publishing sensitive information like phone numbers):

Process Details

For each version, there are 5 phases:

Propose and agree on timeline
Scope: submit proposals and vote for inclusion
Prototype proposals and vote on their specifications
Review full specification draft
Final publication

Phase 1: Propose and agree on timeline

The default cycle time for a new specification version is one quarter (~12 weeks). Once a timeline for a new version is proposed, it must collect at least 5 positive votes and no negative votes in a 5 day period to become the plan of record. Below you'll find an expected timeline for a given version iteration, but the specifics for a given version will come as part of a roadmap proposal:

Propose and agree on timeline (1 week)
Scope: propose ideas and vote on inclusion (3 weeks)
Prototype proposals and vote on their specifications (6 weeks)
Review full specification draft (1 week)
Final publication (1 week)

Note: the version cycles are typically not run back to back – and there is typically a month in between each cycle – to allow for more experience/feedback about the prior version.

Phase 2: Scope: submit proposals and vote on inclusion

During this phase, contributors may submit proposals, and discuss on the list to get agreement on what features will be in scope for development in this version. Following the details below, anyone may contribute a proposal to the discussion.

For a proposal to be officially recognized:

The contributor/author must have already submitted the OpenSocial Foundation's Contribution Licensing Agreement which licenses his/her contributions and indicates his/her intent to non-assert the final resultant specification. In the case of corporate contributions, the proper document is the OpenSocial Foundation's Corporate Contribution Licensing Agreement.
The proposal must be listed on the "current proposals" page of http://docs.opensocial.org and have a corresponding page on the doc with the proposal details.
For clarity, the subject line for the forum thread should clearly indicate the area of the specification impacted as well as the type of change being proposed.
- Areas of the specification: OpenSocial JavaScript, gadget JavaScript, gadget XSD, markup, templates, REST, etc.
- Types of changes: addition, clarification, breaking change
- NOTE: Given the issues associated with introducing breaking changes, any proposals that involve a breaking change to an API that existed in the prior version MUST indicate "Breaking Change" in the subject as well.
  
  A few examples:
  - New Feature Proposal: OpenSocial Templates
  - Clarification Proposal - gadget XSD - lifecycle events
  - OpenSocial REST Proposal - alignment with Portable Contacts schema - Breaking Change

Proposals that do not gain enough traction to be included in the specification version under discussion may be listed on the v.NEXT wiki page, for discussion at a later time.

Phase 3: Prototype proposals and vote on their specifications

During this phase, a given idea should be prototyped and fully specified for a vote. A prototype implementation is an important milestone to help ensure the specification can be well-defined, and allows more testing against expected use cases.

Please note that all official specification proposals must be submitted as patches (to the JS, HTML, etc) against the canonical copy in subversion. Certainly, discussions leading to a proposal on the list are very appropriate, but, to ensure concise and comprehensive proposals, a change cannot be included until after it has been specified (like in a .patch file).

It is also helpful to consider patching the OpenSocial compliance testing suite.

Phase 4: Review full specification draft

This phase allows for the near-final review of all specification changes that have been accepted for this version. For any discrepancies, the typical 5 votes (and no negative votes) will be required to resolve any differences.

At the end of phase, a vote to make this an official specification will be taken (it will become official with the typical 5 +1's with no negative votes).

Phase 5: Final publication

Once the group has voted to make a specification official, all contributors to that specification must now submit the OpenSocial Foundation's Non-Assert Agreement. Upon receiving the appropriate signatures, the new version is ready for official publication on OpenSocial.org.

Additional Notes

Managing the timeline

Alterations from the plan of record timeline require at least 5 positive votes and no negative votes over a 5 day period from the date of the proposal to change the timeline. Changes to the timeline are typically suggested to allow more time to prototype and work through specifics for "must have" features for a given version.

Roles definition

There are a few different roles of people involved with the OpenSocial specification evolution:

Contributors - authors of proposals and people who provide significant comments (more than just a "+1" vote)
Version Shepherd - manages the timeline, champion of encouraging closure/votes on each proposal to keep us on schedule
Specification Editor - manages the drafts, produces and maintains the final publication and the canonical copy in the subversion repository
Process Manager - manages the overall process, helps curate this process document

Handling errata

Once a specification has been published, in the event that an issue is discovered, a .patch file should be sent to the list proposing the clarification/fix, and can become official after 5 days of review and 5 votes (with no negative votes). Patches for typos may be immediately applied, and the list must be notified.

Backwards compatibility

Given that there are many applications and containers in production, introducing non-backwards compatible changes is very painful. As a general suggestion for good hygiene, proposals should make every effort to maintain backwards compatibility. If breaking changes become a problem, perhaps a limit may be introduced on the number allowed per version.

Changes to this process

Proposals to change this process should be proposed and discussed on the list. For a given change to come into effect, it will need to gather 5 +1's and no negative votes over at least a 5 day period. Depending upon the severity of the change, the group may decide to introduce the change in a future version (especially if it comes up in the middle of a version cycle).

Withdrawal from this process

If a contributor wants to stop participating in work on a particular specification version, the contributor must notify the Specification Editor and the Version Shepherd at their respective email addresses. Before withdrawing, the contributor should contact the Specification Editor to discuss the status of any proposals submitted by the contributor and whether the contributor still intends to submit a patent non-assert with respect to the specification. The Specification Editor can then decide whether modifications to the specification will be necessary. Upon withdrawal, the contributor will not be permitted to submit any further contributions to the specification.

Note that any legal rights a contributor has granted prior to withdrawal will survive, such as any copyright grants or patent non-asserts.

Specification Process