GitHub Operating Guidelines

Foreword🔗

The Society of Motion Picture and Television Engineers (SMPTE) is an internationally-recognized standards developing organization. Headquartered and incorporated in the United States of America, SMPTE has members in over 80 countries on six continents. SMPTE’s Engineering Documents, including Standards, Recommended Practices, and Engineering Guidelines, are prepared by SMPTE’s Technology Committees. Participation in these Committees is open to all with a bona fide interest in their work. SMPTE cooperates closely with other standards-developing organizations, including ISO, IEC and ITU. SMPTE Engineering Documents are drafted in accordance with the rules given in its Standards Operations Manual. For more information, please visit www.smpte.org.

This Standards Administrative Guideline forms an adjunct to the use and interpretation of the SMPTE Standards Operations Manual. In the event of a conflict, the Operations Manual shall prevail.

2 Conformance🔗

The following keywords have a specific meaning in the context of this document:

shall and shall not express a requirement from which no deviation is permitted;
should and should not express a strong recommendation without necessarily mentioning or excluding other choices;
may expresses explicit liberty (or opportunity) to do something;
Note and informative indicates that the associated prose is not indispensable, and can be removed, changed, or added editorially without affecting the scope, or the document's usage.

3 Normative references🔗

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

SMPTE AG-04, Engineering Document Templates url: https://doc.smpte-doc.org/ag-04/main/
SMPTE AG-26, HTML Pub: Tooling and documentation for HTML documents url: https://doc.smpte-doc.org/html-pub/main/
SMPTE AG-27, HTML Pub: Template (Base HTML Repo with Tooling) url: https://github.com/SMPTE/html-pub-template

5 Document repository🔗

5.1 Usage🔗

A GitHub repository is primarily intended for:

tracking issues against engineering documents and publishing Public Committee Drafts (PCD);
managing engineering documents via the HTML Workflow as defined by SMPTE AG-26;
managing non-prose element(s) of engineering documents that are intended to be made publicly available, including source code, XML, JSON, etc.

5.2 Private vs public🔗

A repository can either be:

public; in which case it is accessible by the public
private; in which case it is accessible only by SMPTE Standards Community Members

Unless requested by the project group, repositories are created as public repository.

A public repository should remain public.

Discussions in public repository are not subject to the SMPTE confidentiality policy.

A project group may request that a repository be created as private, or made private.

A repository that is private shall not be made public, unless explicitly approved by the Standards Vice-President as provided by the SMPTE confidentiality policy.

In the event that a public repository is created when a private repository already exists, the private repository should be archived and -private appended to its name.

5.3 Creation🔗

A repository is created only on request to sent to githubsteering@smpte.org.

6 Repo Types🔗

6.1 Main Document Repo🔗

6.1.1 General🔗

There is one public repository for all editions and stages of a document. This repo is primarily used for collecting issues from the public.

The main benefit of this repo is that anyone in the community may make a comment (as an issue) about a document without needing to be a SMPTE participant, as long as they are a GitHub user.

This repo may change via a PR for publication of a PCD, and back to a basic issue tracking repo via a PR after completion of a PCD. For guidance on this, see SMPTE AG-22

6.1.2 Naming🔗

The syntax for repo naming is:

("rp" | "st" | "eg")<document root number> "-" <document part>

EXAMPLE —⁠ The repository for the document "ST 2067-105" is named st2067-105

6.2 HTML Publishing Document Repo🔗

6.2.1 General🔗

There is zero or one private HTML document repository for all editions and stages of a document, created from the template at SMPTE AG-27 as defined by SMPTE AG-04.

This repo is used to maintain the HTML source of a document, if one exists, and any additional elements that do not require their own repositories. The workflow for this document process is managed and documented at SMPTE AG-26.

Issues may not be collected in this repo, and the GitHub issue tracker is disabled as such. Editors should always be aware of issues in the Main Document Repo, which may come from the public.

Currently, these repos will always remain private.

6.2.2 Naming🔗

The syntax for repo naming is:

("rp" | "st" | "eg")<document root number> "-" <document part> "-private"

EXAMPLE —⁠ The repository for the HTML workflow of the document "ST 2067-105" is named st2067-105-private

7 User access🔗

7.1 GitHub Teams🔗

Users shall be set into varios GitHub Teams based on need, such as:

One team per TC
One team for ST
One team per TC chair team

7.2 GitHub Permissions🔗

Users and Teams shall have the permissions:

Parent TC team -> read
Parent TC chairs team -> admin
Project group chairs/editors (as contributors) -> maintain

8 GitHub workflow 🔗

Project groups should adhere to the following rules:

one or more editors are responsible for making modifications to the repo;
every substantial modification should be done through a pull request;
a pull request should require at least one approval from a project group member before being merged;
a pull request should only be merged with the consensus of the project group, which can be obtained using the following methods:
1. offering the pull request for a review period and the review period resulting in no substantial objections (a review period of 2 weeks is recommended);
2. seeking explicit project group consensus, e.g. during a meeting or via email;
3. granting the editor(s) to make modifications without explicit project group consensus, e.g. early in the development of the document.