GitHub Workflow
We make use of some common practice for branch and tag naming in order to maintain consistency between specifications and to ease development of tools which depend upon them (such as test suites and documentation rendering).
This NMOS template specification uses this practice, and can be useful when creating a new specification repo.
The following patterns are used for Git branches:
- v#.#.x
- Example: v1.0.x
- Example: v2.5.x
- v#.#-dev
- Example: v1.1-dev
Branches ending in ‘.x’ are used for published versions of specifications which contain one or more Git tags or ‘releases’.
Branches ending in ‘-dev’ are under active development and are used for work in progress on the next major or minor version of the specification.
We do not make use of the 'main' branch. This should be deleted from specification repositories, and the default branch set to the most recent ‘.x’ branch.
When a new version is ready, a ‘tag’ should be created in the relevant ‘.x’ branch. If a ‘.x’ branch does not yet exist, then it may be necessary to rename an existing ‘-dev’ branch (see Maintaining a Specification below).
Multiple tags may exist on a single ‘.x’ branch, but these should correspond only to ‘patch’ releases which fix bugs or update documentation.
For example, the following releases may exist on a ‘v1.5.x’ branch:
- v1.5.0
- v1.5.1
- v1.5.2
- etc.
Where a ‘pre-release’ is required, a new tag may be created on the ‘-dev’ branch provided it indicates in the tag name that it is a pre-release (ie. beta or ‘rc’), and that the release is identified as a pre-release via the GitHub release user interface.
All specification development (including feature addition, bug fixes and documentation changes) should be carried out on the most recent ‘-dev’ branch. This ensures that the next major or minor release will include all fixes which have been made to earlier versions once it is released.
Specification maintainers are permitted to ‘backport’ these fixes onto earlier versions of the specification if they do not constitute a feature addition or breaking change as-per the semantic versioning policy (typically bug fixes and documentation updates). In order to do this, each relevant Git commit can then be ‘cherry-picked’ using Git at the command line onto any earlier ‘.x’ branches which they are relevant to.
Changes should only be applied directly to a ‘.x’ branch (rather than first applying to a ‘-dev’ branch) if they are not applicable to any future versions of the specification. Please check that any pull requests made against the repository will merge into the correct branch before approving them. GitHub branch protection rules should be used to help enforce this.
A typical workflow over the lifetime of a specification is outlined below:
- Repository created and ‘master’ branch renamed to ‘v1.0-dev’.
- Or start by copying the template at https://github.com/AMWA-TV/nmos-template, which has this default.
- Development work carried out.
- ‘v1.0-dev’ renamed to ‘v1.0.x’, a tag created called ‘v1.0.0’
- A GitHub release may also be made, especially to support AMWA’s publishing a Specification.
- ‘v1.1-dev’ branch created at the top of ‘v1.0.x’ for future development.
- Documentation fixes for v1.0 are applied via a pull request to ‘v1.1-dev’.
- The maintainer backports these documentation fixes onto ‘v1.0.x’ by using ‘git cherry-pick’ and resolving any conflicts.
- A new version is released on the ‘v1.0.x’ branch using the tag ‘v1.0.1’.
- This may also require AMWA to update their links (see BCP-001.1)
- Further new features are added to the ‘v1.1-dev’ branch.
- ‘v1.1-dev’ renamed to v1.1.x’ and a tag created called ‘v1.1’.
- ‘v2.0-dev’ branch created at the top of ‘v1.1.x’ for new development work on a breaking change.
The following diagram shows this workflow, as well as the AMWA specification process (see BCP-001.1):
Specifications are rendered to HTML and servered from https://specs.amwa.tv/.
This happens in the .render/ directory, and the details of which branches and releases should be rendered are set in .render/_config.yml
Renders can be performed manually (contact an admin for details) and are carried out automatically on a push using a GitHub Action workflow defined in .github/workflows/render.yml.
Correct rendering requires that
- The Specification uses RAML and JSON Schema, JSON examples of REST calls, and Markdown documentation
- RAML files are in APIs/ with extension '.raml'
- Schemas are in APIs/schemas with extension '.json'
- JSON examples in examples/, with extensions '.json'
- Documents are in docs/, with file names starting '#.#. ' and ending '.md'
If you set up a repo from the template at https://github.com/AMWA-TV/nmos-template this will be put in place for you.
Specification maintainers should please work with NMOS Steering and the Networked Media Incubator chair to ensure everything is consistent.