Status of this Document
- Michael Appleby , Yale University
- Tom Crane , Digirati
- Robert Sanderson , J. Paul Getty Trust
- Jon Stroop , Princeton University Library
- Simeon Warner , Cornell University
- 1. Overview
- 2. Community Process
- 3. Editors’ Process
- 4. Editorial Team Membership and Selection
- 5. Change Log
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 and implementing products. The second part describes the processes that the editorial team use 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.
2. Community Process
2.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.
2.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.
2.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.
2.4 Community Review
New versions of specifications at or above 1.0 must be reviewed at an open meeting, to which the community is invited. These meetings will be announced on IIIF-Discuss, IIIF-Announce and other relevant community email lists. Such meetings must occur at least once per year, and should occur twice. The specifications will be frozen for at least two weeks prior to all review meetings, and this review period will be announced to the same lists as above. For patch level releases, that only make clarifications, a community call (or series of calls) is considered a sufficient venue for a 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.
Objections should be registered in advance of the review meeting. Attendance at the review meeting is not required, but it should be noted that the review meeting is intended to be a platform for discussing any final concerns. Therefore, lack of attendance is likely to reduce the chances of an objection resulting in changes to a specification which has already been subject to the authorship, editorial, and reference implementation processes described above.
The editors shall ensure that there is a response to, and, where possible, resolution of any objections raised. The editors are 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.
2.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.
3. Editors’ 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.
3.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.
3.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.
3.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.
4. Editorial Team Membership and Selection
Per the Memorandum of Understanding that established the IIIF Consortium, the editors may nominate additional editors at any time. All current editors must agree before an invitation is issued. Editors will chose from participants within the community and/or experts willing to lend their knowledge and experience to new specifications. Opportunities to better the gender, race, and age balance of the existing editorial team will also be a consideration. New editors must be approved by the IIIF Executive Group.
There is no set number of editors, but this does not mean that the number of existing editors will not be taken into account when considering new editors. The existing editors will seek out new or additional editors when they are lacking knowledge or significant empathy for use cases in an area that the community has agreed is important.
Editors must agree to all of the processes set out in this document, including attendance at meetings, and to the intellectual property conditions under which the specifications are published. They are responsible for confirming that these conditions are also acceptable to their employer, where applicable.
It is not expected that every editor comment on every issue, though they should make every effort to do so. See Acceptance Criteria for Merging Changes.
Editors may be dismissed from work on a specification, or the editorial group altogether, when they fail to meet the expectations of their colleagues, as described here.
5. Change Log
|2017-03-17||Updates to sections 1 and 2.1 (@srabun, @azaroth, @zimeon, @tcramer)|
|2015-12-22||First release (@mikeapp, @tomcrane, @azaroth42, @jpstroop, @zimeon)|