Merge pull request #1057 from semanticarts/release/12.1.0

Release/12.1.0

Author: rjyounes

README.md

@@ -1,7 +1,6 @@
 ![gist logo](./gist-logo.png)
 
-About gist
-=====
+# About gist
 
 gist is Semantic Arts' minimalist upper ontology for the enterprise. It is designed to have the maximum coverage of typical business ontology concepts with the fewest number of primitives and the least amount of ambiguity.
 
@@ -11,10 +10,11 @@ You can also contribute to gist by adding your comments to [issue discussion thr
 
 gist is free and open to the public under the [Creative Commons 3.0](http://creativecommons.org/licenses/by-sa/3.0/) attribution share-alike license. In addition to the conditions of this license, we require that any concepts used from gist remain in the gist namespace, and that you do not define your own term definitions in the gist namespace.
 
-For more information on gist and to download the current or previous versions of gist, see the [Semantic Arts website](https://www.semanticarts.com/gist).
+[Download the latest version of gist](https://w3id.org/semanticarts/ontology/gistCore).
 
-Documentation
------
+For more information on gist and to download previous versions, see the [Semantic Arts website](https://www.semanticarts.com/gist).
+
+## Documentation
 
 We provide a number of resources for learning more about gist.
 

bundle.yaml

@@ -63,54 +63,55 @@ actions:
   message: "Validating ontology via SHACL."
   type: "shacl"
   inference: "none"
-  source: "{input}"
+  source: "{input}/ontologies"
   includes:
     - "*.ttl"
   shapes:
     source: "{input}/validation/shapes/ontologyShapes.ttl"
 - action: "verify"
-  message: "Verify ontology via queries."
+  message: "Verifying ontology via queries."
   type: "construct"
   inference: "none"
-  source: "{input}"
+  source: "{input}/ontologies"
   includes:
     - gistCore.ttl
   stopOnFail: false
-  target: '{input}/validation'
+  target: "{input}/validation"
   queries:
-    source: '{input}/validation/queries'
+    source: "{input}/validation/queries"
     includes:
-      - '*_construct.rq'
+      - "*_construct.rq"
 - action: "mkdir"
   directory: "{output}"
 - action: "copy"
   message: "Substituting version numbers."
-  source: "{input}"
-  target: "{output}"
+  source: "{input}/ontologies"
+  target: "{output}/ontologies"
   replace:
     from: "X.x.x"
     to: "{version}"
   rename:
     from: "(.*)\\.ttl"
     to: "\\g<1>{version}.ttl"
   includes:
-    - gistCore.ttl
-    - gistMediaTypes.ttl
-    - gistPrefixDeclarations.ttl
-    - gistSubClassAssertions.ttl
+    - "*.ttl"
+  excludes:
+    - gistValidationAnnotations.ttl
 - action: "definedBy"
   message: "Adding rdfs:isDefinedBy."
-  source: "{output}"
-  target: "{output}"
+  source: "{output}/ontologies"
+  target: "{output}/ontologies"
   includes:
     - "*.ttl"
 - action: "sparql"
   message: "Generating rdfs:label and rdfs:comment for backward compatibility."
-  source: "{output}"
-  target: "{output}/rdfsAnnotations.ttl"
+  source: "{output}/ontologies"
+  target: "{output}/ontologies/rdfsAnnotations.ttl"
   format: "turtle"
   includes:
     - "*.ttl"
+  excludes:
+    - gistValidationAnnotations.ttl
   query: >
     prefix gist: <https://w3id.org/semanticarts/ns/ontology/gist/>
     prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
@@ -137,16 +138,16 @@ actions:
 - action: "transform"
   message: "Turtle serialization."
   tool: "serializer"
-  source: "{output}"
-  target: "{output}"
+  source: "{output}/ontologies"
+  target: "{output}/ontologies"
   includes:
     - "*.ttl"
   rename:
     from: "(.*)\\.ttl"
     to: "formatted_\\g<1>.ttl"
 - action: "move"
-  source: "{output}"
-  target: "{output}"
+  source: "{output}/ontologies"
+  target: "{output}/ontologies"
   includes:
     - "formatted_*.ttl"
   rename:
@@ -155,8 +156,8 @@ actions:
 - action: "transform"
   message: "RDF/XML serialization."
   tool: "xml-serializer"
-  source: "{output}"
-  target: "{output}"
+  source: "{output}/ontologies"
+  target: "{output}/ontologies"
   rename:
     from: "(.*)\\.ttl"
     to: "\\g<1>.rdf"
@@ -165,8 +166,8 @@ actions:
 - action: "transform"
   message: "JSON-LD serialization."
   tool: "json-serializer"
-  source: "{output}"
-  target: "{output}"
+  source: "{output}/ontologies"
+  target: "{output}/ontologies"
   rename:
     from: "(.*)\\.ttl"
     to: "\\g<1>.jsonld"

docs/.markdownlint.json

@@ -1,6 +1,6 @@
 {
     "default": true,
-    "MD003": { "style": "setext_with_atx" },
+    "MD003": { "style": "atx" },
     "MD013": false,
     "MD024": { "siblings_only": true },
     "MD036": false, 

docs/ChangeAndReleaseManagement.md

@@ -1,5 +1,4 @@
-Change and Release Management <!-- omit in toc -->
-=====
+# Change and Release Management <!-- omit in toc -->
 
 - [Review and Triage of Outstanding Issues](#review-and-triage-of-outstanding-issues)
 - [Workflow: Implementation, Pull Requests, and Merges](#workflow-implementation-pull-requests-and-merges)
@@ -8,56 +7,51 @@ Change and Release Management <!-- omit in toc -->
 
 This document describes the Semantic Arts change and release management process for gist.
 
-Review and Triage of Outstanding Issues
------
+## Review and Triage of Outstanding Issues
 
-- Semantic Arts ontologists meet twice monthly in order to review and triage GitHub issues and plan releases. (Refer to [*Contributing*](Contributing.md) for guidelines on submitting an issue.)
+- Semantic Arts ontologists meet twice monthly to review and triage GitHub issues and plan releases. (Refer to [*Contributing*](Contributing.md) for guidelines on submitting an issue.)
 - Issues are categorized in one of three ways:
   - **Will not implement**
-    - Label with one of the `closed` values: already resolved, can't reproduce, completed, duplicate, invalid, won't fix.
-    - For duplicate issues, add the earlier issue number in a comment.
+    - Add the reason in a comment. For duplicate issues, add the earlier issue number in the comment.
   - **Will implement**
     - Smaller issues:
-      - Assign an implementer, who could be external to SA under certain circumstances.
+      - Assign an implementer.
       - Assign or re-assign priority, impact level, and effort level.
-      - Tentatively assign to a release project. May be reassigned to a later release project as needed. The assigned issue should be added to the "To do (assigned)" column of the project board.
-      - Where possible, determine and document the resolution to be implemented and apply the label `status: implementation specified`.
+      - Tentatively assign to a release project. May be reassigned to a later release project as needed. The assigned issue should be added to the "To Do (Assigned)" column of the project board.
+      - Determine and document the resolution to be implemented and apply the label `status: implementation specified`.
       - The assigneee implements as specified and submits a PR. See [*Contributing*](Contributing.md#submitting-a-pull-request-pr) for details.
     - To address larger, major, or broader issues (e.g., rewriting a portion of the ontology, revising all annotations), a small, ad hoc working group of volunteers will be formed.
-      - The label `status: in review` is applied.
+      - The issue is moved into the "To Do (Assigned)" column.
       - A group leader should be selected and assigned to the issue.
       - Each group determines their own work schedule and process. There is no deadline or target date for finalizing a proposal.
-      - Once the group has developed a proposal, it will be submitted as a PR and presented during one biweekly meeting, in either order or simultaneously. This does *not* open up the entire work of the subgroup to be rehashed. If you have strong feelings about the issue you should join the working group.
-      - The full group may suggest revisions, which the small group will reconvene to consider, but may or may not adopt.
-      - Once the PR has been finalized and passed through the normal review process, it will be incorporated into the release schedule, generally either the next major or minor release.
+      - Once the group has developed a proposal, it will be submitted as a PR and presented during a biweekly meeting, in either order or simultaneously. This does *not* open up the entire work of the subgroup to be rehashed. If you have strong feelings about the issue you should join the working group.
+      - The full group may propose revisions, which the small group will reconvene to consider but is not obligated to adopt.
+      - Once the PR has been finalized and passed through the normal review process, it will be incorporated into the release schedule for either the next major or minor release as appropriate.
   - **Needs further review**
     - This case is similar to the "will implement" case, in that an assignee is designated to carry the discussion forward at a subsequent meeting. The difference is that here it is not yet agreed whether or how the issue will be addressed. Labels are applied as above, including `status: in review`.
-
-Workflow: Implementation, Pull Requests, and Merges
------
+- Fast-tracking. Some issues are small and non-controversial enough to bypass the group triage sessions. (This is admittedly not entirely objective.) These are labelled `fast-track` and put into the "To Do" column even if assigned. Anyone interested in implementing an unassigned, fast-tracked issue may self-assign the task.
+  
+## Workflow: Implementation, Pull Requests, and Merges
 
 - See [*Contributing*](Contributing.md).
 
-Versions and Version Numbering
------
+## Versions and Version Numbering
 
-Version numbers are of the form `X.x.x` (major.minor.patch). We follow [Semantic Versioning 2.0.0](https://semver.org/) as a guideline, but adjust as needed.
+Version numbers are of the form `X.x.x` (major.minor.patch). We follow [Semantic Versioning 2.0.0](https://semver.org/) as a guideline, adapting for ontology development.
 
 - **Major:** Non-backward-compatible, breaking changes, including inferencing, queries, and data conversion.
   - Examples: adding a restriction, domain, range; adding language tags to annotations.
-  - Major changes should have a significant impact aside from technically modifying inferencing, if the latter is low-impact. For example, in gist 11.1.0 we removed the restriction on `gist:PhysicallyIdentifiableItem` stating that it must have an identifier. Technically, this impacts inferencing, but we considered this so low impact that it was classified as a minor change.
-
+  - Large changes, such as introducing a new module, are not in and of themselves major changes; they are major updates only if they impact the semantics of existing terms.
 - **Minor:** New, backward-compatible functionality. Includes *any* non-major addition to the ontology, even annotation properties or introduction of a new module.
-  - Examples: adding a class or property; adding a `domainIncludes` annotation; deprecation of a term - see the [*Deprecation and Deletion Policy*](DeprecationAndDeletionPolicy.md).
-
-- **Patch:** No new functionality other than bug fixes.
+  - Examples: adding a class or property; adding a `domainIncludes` annotation; deprecation of a term. - See the [*Deprecation and Deletion Policy*](DeprecationAndDeletionPolicy.md).
+- **Patch:** No new functionality other than bug fixes and infrastructure changes that affect process but not the ontology itself.
   - Correction of an error, even if not backward-compatible, does not require a major release. The expectation is that users will not have implemented against an obvious error. This would be a patch.
-  - Examples: Fixing a typo in an annotation; changing a property that was incorrectly defined as inverse functional rather than functional.
+  - Examples: Fixing a typo in an annotation; changing a property that was incorrectly defined as inverse functional rather than functional; modification of the bundle configuration.
 
-A minor or patch version should require only that the user update the version number in the extension ontology's import statement; otherwise, no other changes are required to retain existing functionality.
+A minor or patch version should require only that the user update the version number in the extension ontology's import statement; no other changes are required to retain existing functionality.
 
-Release Schedule
------
+## Release Schedule
 
 - **Major versions** are released on an ad hoc basis when there is a major update, but no more than once every six months.
-- **Minor versions** are (aspirationally) released once per quarter.
+- **Minor versions** are released approximately once per quarter.
+- **Patch versions** are released for urgent bug fixes.