Development of CDO Ontologies

This page houses practices followed for development of CDO ontologies. It is the result of needs identified over the early years of CDO ontologies’ socialization and software review processes. Before the 1.0.0 release of the CDO ontologies, it is likely practices on this page will continue to adapt as workflows are refined.

Review checklists

GitHub repositories for CDO ontology development use the following checklist templates for coordinating the issue’s progression with the respective ontology committee. To enable GitHub progress-tracking (based on checkbox counts), these templates are inlined as edits into the initial Issue or Pull Request description, as an edit by OC Chair or Coordinator.

Due to a display issue with website font colors, the checklists are presented in the CONTRIBUTE.md file in the website’s source repository, here.

Branching

GitHub repositories in CDO follow two branching practices:

“Git-flow” branching

(Link)

The “Git-flow” branching model used by CDO is based on the description by Vincent Driessen, dated 2010-01-05. Repositories following this branch model generally expect most development to be done in “Feature” branches, branching off of develop. The “Primary” branch (typically named master or main) designates releases with tags and the GitHub release-list interface.

In this branching model, pull requests should target the develop branch, not the primary branch.

The head of the primary branch is typically the current release. There may be some non-release commits made on the primary branch due to needing to program components of GitHub interface elements.

“Continous-release” branching

(Link)

This branching model is used for repositories that do not designate releases. The head of the primary branch (master or main) is the “Current release.”

In this branching model, pull requests should target the primary branch.

Testing

Testing prereleases

The CDO ontology Git repositories (including CASE’s ontology repository and UCO’s) follow the “Git-flow” branching model. There is additional consideration put into processing the develop and feature branches:

Part of the testing process for the ontology is assessing impact of proposals, across tooling and existing example data. To assist with this review, CASE provides “Prerelease” ontology builds, available here:

These are monolithic and syntax-normalized builds of the CASE and UCO ontologies. Their states are used to review each of the CASE examples, and their validation SHACL results are stored as files alongside the examples’ source materials. For instance, here are the current validation results for the website’s Asgard example:

CASE-develop.ttl is built according to develop branch states of CASE and UCO, and thus incorporates all of the proposals that are committee-approved and staged for the next release. CASE-unstable.ttl follows an implementation practice that is, well, unstable: Most, or all, proposals under consideration are merged into one branch, before committee review or approvals that would see the proposals merged into develop.

CDO ontologies maintain a -Archive Git repository (CASE’s, UCO’s), whose primary functions are these:

  1. Serve an unstable branch that represents every proposal under committee consideration.
  2. Store an archive of every prior state of the unstable branch.

(The -Archive repositories are not “GitHub forks”, in order to prevent interface confusion from Pull Requests. They do, however, share the master and develop branch histories.)

What makes the unstable branch worth its own archive repository is the branch will not guarantee preservation of its own Git history. Feature branches split off of develop, but do not have a single stable joining point in the ontology development repository where all of their effects can be considered in aggregate. Yet, it is important to discover when in-flight proposals might conflict with one another, and sometimes this is only visible when considering all at once. Meanwhile, the order in which these branches are tested might not be the order in which they are voted upon and accepted into develop by the committee.

The unstable branch will be reset to develop, by the Ontology Committee Chair, Coordinator, or Product Manager, with some left-undefined frequency. To ensure access to prior states of the unstable branch, the -Archive repository will maintain named branches at the time of reset, e.g. archive/unstable-2022-04-01. (This can benefit users who test by using Git submodules and/or Git Bisect, rather than website downloads. The CASE-Examples repository and CASE website both track with submodules.)

To summarize, if a developer wishes to test against some “Prerelease” state: