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 at: http://groups.google.com/group/opensocial-and-gadgets-spec/topics 


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 impelementable 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 (THIS FORM WILL BE AVAILABLE IN THE COMING WEEKS). Additionally, prior to finalizing the specification, all contributors must submit the OpenSocial Foundation non-assert agreement (THIS FORM WILL BE AVAILABLE IN THE COMING WEEKS).

Process Details

For each version, there are 5 phases:

1. Propose and agree on timeline
2. Scope: submit proposals and vote for inclusion
3. Prototype proposals and vote on their specifications
4. Review full specification draft
5. 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:

1. Propose and agree on timeline (1 week)
2. Scope: propose ideas and vote on inclusion (3 weeks)
3. Prototype proposals and vote on their specifications (6 weeks)
4. Review full specification draft (1 week)
5. 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: 

1)     The contributor/author must have already submitted the OpenSocial Foundation Contributor Licensing Agreement (CLA) indicating the intent to non-assert and license his/her contributions.

2)     The proposal must be listed on the “current proposals” page of wiki.opensocial.org and have a corresponding page on the wiki with the proposal details.

3)    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

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 patent non-assert document (THIS FORM WILL BE AVAILABLE IN THE COMING WEEKS). 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).