Specification Process

Owned by Mark Halvorson (Deactivated)
Last updated: Mar 28, 2014 by Matthew Marum
7 min read

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.

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

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 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.

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

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:

  1. The proposal 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.

      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 moved to v.NEXT, 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 (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.

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, the OSF WG Administrator will then make the new version 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)
  • OSF WG Administrator - manages the drafts, produces and maintains the final publication and the canonical copy in the Github repository
  • Release 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 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.

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 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.