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 (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 lists and repositories (not behind closed doors)
• All proceedings are captured in a public archiveIndividuals represent themselves, not companies

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

...

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 Agreementsign 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, each form has a publicly viewable snapshot of the entries (sanitized so we're not publishing sensitive information like phone numbers):

• OpenSocial Foundation's Contribution Licensing Agreement Submissions
• OpenSocial Foundation's Corporate Contribution Licensing Agreement Submissions
• OpenSocial Foundation's Non-Assert Agreement Submissions

Process Details

For each version, there are 5 the list of IPR signees and corresponding issues are included in our public repository.

• https://github.com/OpenSocial/spec/tree/master/ipr

Process Details

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:

1. Propose and agree on timeline
2. Scope: submit proposals and vote for inclusion
3. Prototype proposals and vote on their specifications
4. Acceptance of proposed changes by OSF WG Administrator
5. Review full specification draft
6. Final publication

For each maintenance release, we follow an abbreviated process:

1. Scope: submit Specification bugs or Pull Requests that fix specification bugs for inclusion in current maintenance release
   1. A specification bug is any issue that requires normative changes to remove design flaws or add clarity to the specification
   2. Submit Specification bugs using the OpenSocial Spec repository Issue Tracker
2. Acceptance of proposed changes by OSF WG Administrator
3. Review full specification draft
4. Final publication

Maintenance releases are published as needed.  Prototypes for changes are not required but no new features are allowed.

Phase 1: Propose and agree on timeline

...

For a proposal to be officially recognized:

1. 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 wiki.opensocial.org and have a corresponding page on the wiki with the proposal detailsproposal should have a Pull Request in the OpenSocial Spec Github repository and a corresponding thread on the OpenSocial and Gadgets Specification list.
2. 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.

     Panel
     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 moved to v.NEXT wiki page, 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.

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.

...

 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.

Phase 4: Acceptance of proposed changes by OSF WG Administrator

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.

Phase 5: 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 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).

Phase

...

6: 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 the OSF WG Administrator will then make the new version ready for official publication on OpenSocial.org.

...

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

...

Once a specification has been published, in the event that an issue is discovered, a .patch file Pull Request should be sent to the list submitted proposing the clarification/fix , and 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 must should be notified.

Backwards compatibility

...

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 OSF WG Administrator at their respective email addressesaddress. Before withdrawing, the contributor should contact the Specification Editor OSF WG Administrator to discuss the status of any proposals submitted by the contributor and whether the contributor still intends to submit a patent non-assert sign the OpenSocial IPR (if they haven't already) with respect to the specification. The Specification Editor 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.

...