This document describes the process by which specifications are designed and written within the IIIF community. The first part describes the expected participation of the community throughout the process, including gathering real world use cases, discussing solutions, implementing products, and the role of the Technical Review Committee (TRC). The second part describes the processes that the editorial committee uses to ensure that the specifications are of the highest quality possible. The processes are intended to be as transparent and inclusive as possible, while still making progress quickly and responsibly.
Updates to this document are tracked in the change log at the bottom of the page.
1. Community Process
1.1 Proposals and Feedback
Community members should propose and discuss features and changes via IIIF-Discuss, and within Technical Specification Groups if an appropriate group exists. However, there are a few other ways in which the IIIF Community can engage in the specification process. In particular, the IIIF holds a bi-weekly community conference call as well as various Community Group and Technical Specification Group meetings, the details and agenda for which are announced on IIIF-Discuss. Additionally, the iiif.io issues on Github are open, and are especially useful for implementers who want to track the discussion around an issue of interest. Finally, conversations with individual editors are also possible, but are the least practical way to propose changes because the conversation will then have to be repeated to allow community input through one or more of the channels listed above.
Within Technical Specification Groups, consensus for decision-making is sought via discussion and healthy debate. If disagreements arise, proponents of each approach should provide mock-ups, examples, and demonstrate practicality of implementation as well as conformance to accepted design patterns, in order to justify their approaches. These suggestions will be reviewed by other group members and discussed further within the group, on the IIIF-Discuss list, and on technically-focused community calls.
1.2 Use Cases and Support
New specifications and changes to existing specifications must have one or more documented use cases, supported by at least two institutions that either have IIIF-based technology in production or are clearly blocked from doing so, as demonstrated by the use case. In the case of breaking changes, where applicable, the documented use case must clearly demonstrate why the previous approach was flawed or insufficient.
1.3 Evaluation and Testing
In order to be considered ready for final review, new features must have two open-source server-side implementations, at least one of which should be in production. New features must also have at least one open-source client-side implementation, which may be a proof-of-concept.
1.4 Community Review
New versions of specifications at or above 1.0 must be reviewed by the Technical Review Committee (TRC) as representative of the consortium and the community with regards to technical matters. Both the agendas and the notes from TRC meetings will be openly available.
Proposed new specifications will be frozen for at least two weeks prior to all TRC review meetings, and this review period will be announced on IIIF-Discuss, IIIF-Announce and other relevant community email lists. Objections should be registered in advance of the TRC review meeting.
Proposed revisions to specifications must reference a change log as a means to help the community review the changes. This change log should differentiate between backwards compatible changes and breaking changes, and provide a brief summary of each change. See the Image API 2.0 Change Log for an example.
The TRC shall ensure that there is a response to, and, where possible, resolution of any objections raised. The TRC is responsible for considering the severity and importance of any remaining objections, and, ultimately, whether to seek additional community input and continue revision, or to proceed with publication of the new version of a specification.
Once approved by the TRC, new specifications or updates to existing specifications shall then be released by the editors.
1.5 Frequency of Releases
No specification is perfect. New use cases surface, and refinements and clarifications need to be made. As such, specifications are generally considered to be under continuous revision. The editors will decide when new releases are proposed for review based on input from the community, balanced against the need for a degree of stability and consideration of other IIIF priorities.
New IIIF specifications, and the Image and Presentation API specifications beyond their version 2.0.0 releases, follow semantic versioning as defined in the IIIF Versioning Note. It is intended that minor, backwards compatible, releases will not be published more than once per year, and that major releases will not be published more than once every two years.
Specification versions prior to 1.0 should be considered experimental, are not subject to community review, and may be updated with breaking changes at the editors’ discretion.
2. Editorial Committee Process
The key words must, must not, required, shall, shall not, should, should not, recommended, and optional in this document are to be interpreted as described in RFC 2119.
2.2 Process for Suggesting Changes
Editorial collaboration takes place primarily in the iiif.io repository on GitHub. When editors submit changes for revision, they must adhere to the following criteria:
- There should be a Github issue that explains the reason for the change and serves as a platform for discussion. Discussion regarding smaller, primarily word level, changes may take place directly on a pull request in the comments or as line notes.
- The changes must be made in a branch.
- The branch must pass all integration tests before making a pull request.
- A link to the branch (i.e. http://mybranch.iiif.io) must be included in the pull request relevant to the change.
- Changes on the branch should be squashed into one commit, with a reasonable commit message, and one parent commit that is the latest revision. Multiple commits are allowed when they are logical, but this should generally be avoided as it usually indicates that there are too many changes happening on one branch.
- When one or more editors feel that a branch is ready for final consideration, they must label the issue as “Ready for Review” and submit a pull request that references the issue.
N.B.: The current editors will help new editors with this process as necessary. Prior experience with Git or Github must not be considered prerequisite knowledge when considering new editors.
2.3 Acceptance Criteria for Merging Changes
Final voting must take place on a pull request. Non-normative editorial discussion, e.g. to point out changes in language and typos, may also transpire on the pull request, however, any discussion of substantive changes related to the issue must continue on the issue.
In addition to adhering to the guidelines above, there must be agreement about the change among the editors. Agreement is defined as follows:
- There must not be any “-1”s (or similar Emoji) in the latest comment from any editor before a merge.
- A majority of the editors, including the issuer of the pull request, must actively agree (“+1”) on any non-normative change to a specification.
- All but one of the editors must actively agree on any normative change to a specification.
- Even for non-specification content, at least one editor, in addition to the issuer of the pull request, if applicable, must actively agree to any change on the iiif.io website.
The editor that submitted the pull request must not be the editor that merges it.
In the event that an editor disagrees with a merge that has already happened, they should create a new issue that references the change in question, and explains the objection. This issue then serves as the discussion point for the objection which is subject to this same process. Reverts should stay in the repository history, i.e., the process of reverting involve updating the HEAD version to reflect older content, and not erasing or re-writing history.
2.4 Face to Face Meetings
Editors will meet at least four times per year, and all editors must attend at least three of those meetings per calendar year. Every effort will be made to co-locate at least one of the meetings with another meeting at which most of editors are already likely to be present.
The editors must provide a summary of all meetings, and should provide a summary of other interactions (e.g. closed conference calls leading up to a specification review period) at which changes and new specifications are discussed.
3. Change Log
|2018-11-12||Split off membership and added TRC role|
|2017-03-17||Updates to sections 1 and 2.1 (@srabun, @azaroth, @zimeon, @tcramer)|
|2015-12-22||First release (@mikeapp, @tomcrane, @azaroth42, @jpstroop, @zimeon)|