NENA needs a stable place to put the artifacts generated as part of the standards development process that are used by software developers to implement the standard which are tools, rather than the text of the standard itself. The most common artifact is a schema or interface description (YAML file), but there are others. The development process for these artifacts is different than the editing process of a standard. The tools used to create and maintain them is different. This document describes how NENA uses the GitHub tool to maintain these artifacts.
NENA’s repositories SHALL be held permanently at https://github.com/NENA911.
A Version Control System (VCS) is used to track the history of changes as multiple people or teams work on the same project together. VCSes are ubiquitous in the software development industry so multiple programmers can work simultaneously on the same codebase, while tracking and managing multiple versions and providing a way to establish consensus and resolve conflicts. Git is the most popular distributed VCS used today. Git is a free and open source VCS. It allows for developers to see a full timeline of changes, decisions, and progression in one place. Any change can be viewed and, more importantly, easily rolled back. NENA's Development Group (NDG) uses the Git tool GitHub to manage version control for its schemas and interface definitions. This is because a VCS designed for software development is a much more appropriate tool for managing changes to schemas and interface definitions than NENA's traditional means of maintaining a single standing version of a consensus document that includes the normative definition of a schema or interface definition in a static document.
A repository ("repo") in GitHub is a folder (directory) containing one or more files. The artifact itself is a file, but there may be other files such as shell scripts, documents, test cases, other folders, etc. Each file has a revision history which is tracked by GitHub. GitHub commonly has a repository per “project”. In NENA, an API is a project, as opposed to, say, a document. This is because documents may modify any number of APIs, some of which may have been defined in different documents. NENA repositories are not limited to APIs; repositories may be created for other purposes.
A working group requiring a new repo SHALL request that the NENA GitHub Administrator create the repo, including minimum content requirements for the initial readme.md (see Section "Structure").
The GitHub Administrator is at least two (2) individuals designated by the Development Steering Council (DSC) to manage NENA repositories. When there is a vacancy, DSC SHALL appoint a new Administrator within a reasonable amount of time.
Artifacts have versions, which follow the pattern of NENA document versions: <major>.<minor><fix>, where a minor versions of a major version are backwards compatible with each other. The artifact is reviewed as part of a document review process and the merge to “main” only occurs on completion of that process. The <fix> designation is for updates to a version that used the “errata” process defined in NENA-ADM-001.
The version number of an artifact is NOT tied to the same version number of the document that creates or modifies it. The first version of an artifact is always 1.0, regardless of the version of the document that creates it, and the artifact's version is incremented as that document, or other documents, make changes to the artifact. If any document, regardless of whether it is a new document or a major or minor version of an existing document, updates an artifact in a way that is backwards compatible with all minor versions of the current major version of the artifact, then the artifact incremements the minor version and retains the existing major version. As a change to an artifact that is not backwards compatible with other minor versions, by definition, makes the document a major version update, major version updates to artifacts are always major version updates to the document that makes the change. A minor version update to a document could create a new artifact (1.0 version) as long as the artifact is optional to use.
Repositories foster development of artifacts by allowing creation of a “branch”. A branch is effectively a copy of the repository to which changes may be made to any of the files, and specifically the artifacts, without affecting the (default) “main” branch that always represents the latest released version of the repository. Branches may be merged into other branches, including “main”. When a branch is merged to “main”, that is the formal release of the version, and becomes the new release. Older branches are maintained, so that users may download any branch. This is the way versions are maintained: as branches in the repository. An artifact defined in any non-historic NENA document SHALL have a stable link maintained to a branch for that artifact.
The name of a branch is the version the artifact will become as created or modified by a corresponding document. For example, version 3 of a document creates a Major Version of an artifact. Later, version 3.2 of the document updates the artifact in a backwards compatible way. A Minor Version will be created, updates will be made to that branch as development of the 3.2 version of the document proceeds. When the document is approved as version 3.2, the Minor Version branch will be merged into the “main” branch of the artifact. If another document needs to further modify the artifact, a new Minor Version branch will be created in the repository and changes in that branch will be accepted as the development of the other document proceeds.
Users typically “clone” a repo, select or create a branch, and edit files in that branch. The clone is maintained by git as a local copy of the entire repo. When changes to files are made, git tracks the changes. An operation called a “Commit” commits the changes in the repo. The commit memorializes what was changed, who changed it, and when it was changed. A comment may be added to the commit. For NENA documents, comments SHALL be included that summarize the changes. It is possible in some systems to “push” the commit directly to the main repo, but this SHALL NOT be done to a NENA repository. See “Pull Requests” below.
Commits on a branch SHALL indicate in their description the entity that is requesting the change (usually a working group).
Pull Requests are requests from an author to apply a set of changes to a branch. Github manages this process with lots of automation. The Owner approves pull requests as changes are reviewed, similar to how documents are updated. Contrast this with a Push that directly changes the repo branch following a local commit. NENA repos exclusively use Pull requests and SHALL not permit Push operations. Pull requests are reviewed and then merged to the branch.
Pull Requests on a branch SHALL indicate in their description the entity that is requesting the change (usually a working group).
Every repo and every directory SHALL have a readme.md file. Github automatically parses this into a human-readable landing page. The readme MUST contain:
- A description of the artifact
- The owner of the artifact
- Rules for contributing changes. If not otherwise specified, the default rule for a NENA repository SHALL be "Specification Required". The following rules for changes are adopted and adapted from IETF RFC 8126, and have substantially similar meaning:
- Private Use
- Experimental Use
- Hierarchical Allocation
- First Come First Served
- Expert Review
- Specification Required
- Standards Action
- Administrator contact information (with a stable URI) (The Owner of the repo or the Administrator for a development branch)
- Version history
Each version of the artifact SHALL be tagged with the appropriate version number. This SHALL be recorded in the Version History field in the readme. Each version SHALL update the previous artifact. Prior version history is available by browsing branches; for example, if implementers require backwards compatibility or need to implement a legacy version of an artifact for some purpose. Implementers SHOULD always implement the current version of any artifact, and are strongly discouraged from knowingly implementing legacy versions.
The following tags SHALL be used for releases (examples in parentheses):
- Major Version (1.0, 2.0)
- Minor Version (1.1, 1.2)
- Fix (1.2a, 1.2b)
The syntax for Release Tags is:
[Major Version] "." [Minor Version] [Fix Version]
Updates to versions other than the current version SHALL NOT be allowed, unless it is Fix. In some cases, two documents may be developing Minor versions simultaneously; in these cases it is the responsibility of the Owner to referee conflicts and assign Versions.
Major Versions are not backwards-compatible with previous Major Versions.
Minor Versions SHALL be interoperable with all Minor Versions within the same Major Version.
Fixes are inteded to address obvious mistakes in an Artifact. A Fix may or may not be compatible with previous versions and they are intended for obvious mistakes in the Artifact. For example, when there is a typo that prevents an interface from working entirely, or when the artifact was clearly written incorrectly and does not fulfill the requirements of a published standard that created the Artifact. A Fix MAY not be backwards compatible if it addresses an obvious mistake that prevents the Artifact from working as intended. This mechanism SHALL be used very sparingly per the discretion of the Owner to determine whether it is reasonable to issue a Fix. For example, if a Fix is introduced within a short time of a standard being published that produced the artifact, it is probably reasonable to issue a non-backwards compatible Fix. If a Fix is however after an Artifact is published and there is wide commercial availability of services that match the published version of the Artifact--even if that artifact has obvious mistakes--it is probably not reasonable to issue the change as a Fix, and the change should should probably be a Major Version or Minor Version. It is the responsibility of the owner to determine what is "reasonable" under the guidance in this section.
Typically the Owner will be the workgroup that created the repository Fixes SHALL be handled through the NENA errata process [see NENA ADM-001].
Fixes MAY be issued against legacy branches. Fixes against legacy versions are allowed when it is necessary to correct a legacy version. For example, an issue is discovered with a legacy version that is known to have wide commercial availability and there is limited commercial availability of the current Version. Such cases should be very rare and Owners should discourage them, and allow them only when absolutely necessary.
A NENA repository has an Owner. The owner is normally the working group that created the repo, or its successor. Only DSC can change the Owner.
The Owner of the main branch has final say on the main branch. This means that another working group making changes on a development branch must have assurance that the Owner intends to approve changes in the development branch. When in doubt, the working group maintaining a development branch may request the Ownder conducts an approval ballot. Approval of the ballot indicates consensus of the Owner working group to release the version approved by the development working group.
Development branches are created the working group that is creating or changing the artifact. Every development branch must have one or more assigned Administrators.
GitHub has the ability to tag specific points in a repository’s history as being important. A tag is a short string attached to a specific commit.
NENA Artifacts and working branches use tags to indicate released versions and review cycles. Other uses of tags are up to the development or owner working group. When a document undergoes a review, the version of the artifact that is being reviewed gets a tag that matches the review. Tags used for review cycles of an Artifact SHALL be:
- working-group-review
- all-committee-review” (or “all-committee-review-2” or -3, etc)
- public-review” (or “public-review-2” or -3, etc.)
All commits to a working branch SHALL be tagged with the name of the corresponding document.
When a document is approved for publication, and the branch is merged to main, the merged version SHALL be tagged with the document name that created or modified the Artifact. This allows an implementor to know what the most current released version is: the tagged version on “main”.
NENA should make good use of the issues feature of GitHub. An issue may be a bug report, a feature request, a memory jogger or a strategic issue being worked by multiple contributors. Any working group member may create an issue. Issues are managed by working group co-chairs or co-chairs may delegate issue management to a skilled member or group of members of the working group. Working group members are encouraged to use issue templates, and working groups are encouraged to create templates for frequently occurring issue sources beyond the default bug report and feature request templates. When creating or working issues, contributors are encouraged to use permalinks to link to artifacts or other files in a repo. Crosslinking of issues, when they are related, is also encouraged. Larger issues should include a checklist to manage multiple aspects of one issue.
Some working groups use GitHub issues to manage issues that occur within the document development process, beyond the artifacts that are maintained in GitHub. Similar to a “parking lot”, the issues mechanism mechanizes remembering, processing and documenting item the working group agreed “to do”. This does require non-developer working group members to learn how to use at least the issue management facilities of GitHub.
A file containing formal interface definitions, schemas, documents, examples, scripts or other content that is related to a standard and used by developers to implement the standard. Some artifacts may be included by reference in a standard. Within NENA, Artifacts are stored in a Git repository. Groups of Artifacts often describe an Application Programming Interface (API).
[1] Github.com. "About Github". Retrieved 17 March 2022 at: https://docs.github.com/en/get-started/using-git/about-git
[2] Git Project. "About Git". Retrieved 17 March 2022 at: https://git-scm.com/
[3] Guidelines for Writing an IANA Considerations Section in RFCs. Retrieved 11 April 2022 at: https://www.rfc-editor.org/rfc/rfc8126.html#section-4.3
[4] NENA-ADM-001.5a-2021, "NENA Development Group Organizational Structure and Operational Procedures". Retrieved 19 May 2022 at: https://www.nena.org/page/NENAOrgStructure