OpenSocial Specification Definition Process
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.
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):
The discussion forum for new contributions and archive of past discussions is located in the OpenSocial Specification List.
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).
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 sign the individuals must sign the CLA which incorporates the IPR Agreement and this Specification Development Process.
As an aside, in the interest of transparency and ease of shepherding, the list of IPR signees and corresponding issues are included in our public repository.
A specification release that changes the Major or Minor version number is considered a feature release. A maintenance release is for the inclusion of normative changes to the specification that clarify or remove design errors or flaws in the specification. Non-normative changes (editorial) do not need a formal process though contributors still need to sign the OpenSocial CLA.
For each feature release, there are 6 phases:
For each maintenance release, we follow an abbreviated process:
Maintenance releases are published as needed. Prototypes for changes are not required but no new features are allowed.
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:
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.
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:
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:
|
Proposals that do not gain enough traction to be included in the specification version under discussion may be listed moved to v.NEXT, for discussion at a later time.
During this phase, a given idea should be prototyped and fully specified (with an open spec pull request) 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. The submitter of the Github pull request will also need to make sure they have digitally signed the OpenSocial CLA or their changes are ineligible for inclusion.
Each release will have a designated OSF WG Administrator. The Administrator for the release will accept pull requests for features that have 5 +1 votes and no -1 votes. Bugs do not require a vote. Authors must also have signed the OpenSocial CLA. The Administrator may also make non-normative edits to proposals as they are included into specification.
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 called by OSF WG Administrator to make this an official specification will be taken (it will become official with the typical 5 +1's with no negative votes).
Once the group has voted to make a specification official, the OSF WG Administrator will then make the new version ready for official publication on OpenSocial.org.
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.
There are a few different roles of people involved with the OpenSocial specification evolution:
Once a specification has been published, in the event that an issue is discovered, a Pull Request should be submitted proposing the clarification/fix and should be cross posted to mailing list. It 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 should be notified.
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.
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).
If a contributor wants to stop participating in work on a particular specification version, the contributor must notify the OSF WG Administrator at their email address. Before withdrawing, the contributor should contact the OSF WG Administrator to discuss the status of any proposals submitted by the contributor and whether the contributor still intends to sign the OpenSocial IPR (if they haven't already) with respect to the specification. The OSF WG Administrator 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.