Version History

Contents

The following rules MUST be followed when using this document; these are taken from IETF RFC 2119 (simplified):

1. MUST: This word means that the definition is an absolute requirement of the specification.

2. MUST NOT: This phrase means that the definition is an absolute prohibition of the specification.

3. SHOULD: This word means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications MUST be understood and carefully weighed before choosing a different course.

4. SHOULD NOT: This phrase means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

5. MAY: This word means that an item is truly optional. One user may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product, while another vendor may omit the same item.

Terminology

• IOF ontology expert: person who has a comprehensive and authoritative knowledge of or skill in the development of IOF ontologies

  • Note 1: person is selected by the TOB

  • Note 2: person must have knowledge of description logic (DL) and first-order logic as well as the IOF annotation and development process requirements. In addition, person must have knowledge of Protége and OWL

• construct: refers to an OWL class, object property, or data property

• master branch: main release branch of the GitHub repository

• target ontology: ontology that the provisional ontology will become once it is released

• Xxx: refers to the target ontology name

Overview

Maturity designates an ontology's development status and how it will integrate into the development and release process.

• released indicates that the ontology has been through the entire release and voting process and is now a normative part of the IOF ontologies.

• provisional indicates that the ontology is in development and may contain errors or omissions.

A maturity annotation encompasses an entire ontology. All constructs, axioms, and annotations in that ontology file have the same maturity. The ontology maturity is set to provisional whenever the ontology is being worked on in a branch of the repository, regardless of its released maturity in the master branch. The work will proceed in the working group until they have resolved all the issues and the working group votes for the ontology to be released. It will then go through an IOF review and a TOB vote. The TOB can either release the ontology or have the changes remain provisional, sending it back to the working group with comments and suggestions.

Each working group can have the ontology reviewed by experts in the IOF at any time during the development process. They must push changes to GitHub and inform the experts that they require help on general or specific issues related to the ontology. The experts must review and advise the working group promptly.

Rules

• Provisional ontologies MUST be included in the AboutIOFDev.rdf file in the directory of the target ontology

• Provisional ontologies MUST NOT be included in the related AboutIOFProd.rdf file in the directory of the target ontology

• All constructs, axioms, and annotations under development MUST be in an ontology file with an iof-av:maturity of iof-av:Provisional

• Released ontologies MUST NOT be dependent on provisional ontologies

• For constructs not considered for inclusion in the release, they MUST be in the provisional subdirectory (relative to the target ontology) , and the additions or changes MUST be in a separate file named provisional/Xxx

• The IRI of the added or modified construct MUST match the IRI it will have when it is released

• IF the working group wants to use a version IRI, the ontology in a development branch MUST use a version IRI formatted using YYYYMMFMLNN where F is the first initial, M is the middle initial, and L is the last initial of the person making the change or chair if WG change and NN is a monotonically increasing number for each change in that month

• The TOB MUST select IOF ontology experts from the TOB membership

• Each Working Group MUST be assigned an IOF ontology expert by the TOB

  • The IOF ontology expert SHOULD attend some of the meetings and review recordings

• Each Working Group Review MUST be assigned some of IOF ontology expert(s) by the TOB

  • The working group MUST notify TOB when a review is required on a regular basis

  • The IOF ontology expert(s) MUST raise issues in Jira related to the changes in the ontology to feedback comments to the working group

  • If possible, IOF ontology expert(s) SHOULD not have participated in the reviewed ontology development

  • The expert(s) SHOULD review recordings when necessary

Overall Process

Open

Steps

1. The working group creates a working branch on GitHub

2. The WG sets the ontology maturity to provisional

3. The WG adds or modifies constructs in the ontology

   1. The majority of the ontology development will occur in this step and will be detailed in a future document

4. An optional step allows the WG to separate some constructs that will not yet be considered for release

5. The WG pushes changes to GitHub

   1. Automated CI Jenken's job will check ontology for any automated errors or omissions.

   2. IOF ontology experts will review the ontology periodically, giving advice to the working group on IOF best practices and requirements and answering questions regarding the development process

   3. If issues are found, the working group must go back to step 3 and address the issues

6. The WG votes on the provisional target ontology to be released

   1. If the vote is not successful, the process goes back to step 3

7. The WG changes the maturity to released, and a pull request is created

8. The IOF is made aware of the pull request and allowed to comment on the release candidate for two weeks

9. The working group is allowed to address any issues arising from the WG review; changes are made to the branch for the pull request

10. Two reviewers who are IOF experts review the final release and approve all the changes

11. Once the reviewers approve and the CI process pass, all the merge request requirements are met

12. The TOB votes on the release

    1. Conditional rejection means the TOB believes the ontology needs more work and is not ready for release. The release changes are sent back to the working group as Jira issues

       1. One option is the WG can move some of the constructs to the provisional subdirectory ontology file and merge the changes into the master branch. Target ontology is reverted to the previous state on the master branch.

       2. The work continues at step 3

13. The changes are approved by the TOB, and they are merged into the master branch

Examples