1. Overview

This document outlines the process for requesting and making changes to any of the IDPF's GitHub repositories.

A free GitHub account is required in order to perform the operations described in this document.

This document is not a tutorial on how to use the git version control system. If you are unfamiliar with forking/cloning repositories, committing changes, creating pull requests or performing other operations, please first take the time to review the GitHub documentation.

2. Reporting Issues

The easiest way to request a change is to report an issue. Be sure to include as much information as possible to assist in reviewing your request (e.g., affected document and section and rationale for the change).

If you are not familiar with opening GitHub issues, the following steps will guide you through the process:

Locate the IDPF repository that contains the document you want changed. If you are unsure which your issue applies to, use the EPUB revision repository.
Click on the "Issues" tab.
Check the open issues and/or try some keyword searches to verify that the issue has not already been reported.
Click on the "New issue" button.
Create a short title that meaningfully conveys the issue.
Write a detailed description of the issue, include a proposed resolution if you have one.
Click submit.

Note that you may not receive feedback right away, but that does not mean the issue will not be, or is not being, considered. See the section on evaluation below for more information on why an issue can take a while to get addressed.

3. Creating Pull Requests

GitHub allows users to copy public repositories, make changes to the source markup and submit the changed documents back for consideration. The process of submitting the changed document(s) back is called making a pull request (i.e., asking the owner to pull the changes back in).

Although the EPUB Working Group will review all requests and make any necessary changes, users can submit pull requests with their issues.

Pull requests are most helpful for new additions (e.g., to add a new item to a registry), especially when the request is for a change that the Working Group might not be as familiar with. Creating a pull request does not guarantee the request will be considered any faster, but will expedite the update process.

Pull requests are best done by advanced git users. The process involves forking the applicable IDPF repository, downloading a local copy, updating the affected file(s), committing the changes back to your fork and then creating a pull request in the EPUB repository.

For more detailed instructions about this process, please refer to the following GitHub documentation pages:

4. Evaluation of Requests

The EPUB working group is responsible for evaluating and approving request changes to the EPUB format. Other working groups may be responsible for the various modular specifications that have been developed by the IDPF.

Change requests are typically screened by the applicable working group Chairs prior to bringing to the full working group for review and approval. Issues can be closed without broader review if they are determined to be out of scope, inapplicable, infeasiable or otherwise unimplementable.

The IDPF cannot guarantee a timeline for review and approval of change requests. Some changes can only be made during revisions to the EPUB specifications, regardless of their merit (the IDPF will issue errata between revisions for serious technical issues). Others, such as additions to registries, may be implemented quickly if a key need is recognized.

Depending on the nature of the change requested, approval of the IDPF Board and full membership may also be necessary (e.g., for feature request changes to the EPUB format).

Note that the approval process described in this section does not apply to every repository that the IDPF maintains. For example, some repositories are created for use by subgroups developing new specifications, and those groups have discretion over how they address changes. Similarly, repositories that host guides, samples and other informative documents do not necessarily require a full review of every change request. The IDPF has sole discretion over how its repositories are run.