Merge branch 'develop' into kate/1024

Author: kstudzin

.markdownlint.json

@@ -4,5 +4,6 @@
     "MD007": false,
     "MD013": false,
     "MD024": { "siblings_only": true },
+    "MDO29": { "style": "one_or_ordered" },
     "MD036": false
 }

README.md

@@ -14,7 +14,16 @@ gist is free and open to the public under the [Creative Commons Attribution 4.0
 
 For more information on gist and to download previous versions, see the [Semantic Arts website](https://www.semanticarts.com/gist).
 
-## Documentation
+## Setting up a Local gist Repository
+
+- Clone the [gist GitHub repository](https://github.com/semanticarts/gist.git).
+- Run the script `./tools/setup.cmd`.
+- To work on gist, refer to the following documents:
+  - [Contributing to gist](docs/Contributing.md)
+  - [gist Style Guide](docs/gistStyleGuide.md)
+  - [Contributor Quick Reference](docs/ContributorQuickReference.md)
+
+## gist Documentation
 
 We provide a number of resources for learning more about gist.
 
@@ -23,12 +32,12 @@ We provide a number of resources for learning more about gist.
 Extensive documentation of gist is available in the [gist-doc repository](https://github.com/semanticarts/gist-doc). This repository contains documentation of the [Semantic Arts gist minimalist upper ontology](https://github.com/semanticarts/gist/tree/master) in three formats: narrative, graphical, and Widoco-style.
 
 * **gist Constellations (eBook)**
-  * The organization of the eBook is based around the idea of 'constellations' of classes and predicates that deal with related concepts.  
+  * The organization of the eBook is based around the idea of 'constellations' of classes and predicates that deal with related concepts.
   * epub and mobi formats
 * **gist Constellations (visualizations)**
   * A collection of PNG images built using the [Turtle Editor Viewer](http://semantechs.co.uk/turtle-editor-viewer/).  Each image is made up of a single 'constellation' of classes as described above and shows the classes and their relationships, the literal annotations, and any anonymous classes used in class definitions.
 * **[Widoco](https://github.com/dgarijo/Widoco) documentation**
-  
+
 ### Additional Documentation
 
 * **Videos:** We maintain a library of videos containing gist tutorials and recordings of our monthly gist Council meetings. You can find links to these videos on the [Semantic Arts website](https://www.semanticarts.com/gist/videos/), or directly access the entire catalog on [our YouTube channel](https://www.youtube.com/playlist?list=PLk2kJrehubb4dc3e5Db5Lvv9WMaOhV3V7).

docs/Contributing.md

@@ -0,0 +1,36 @@
+# gist Contributor Quick Reference
+
+This is a quick reference guide to submitting a pull request (PR) to the gist GitHub repository. Refer to the [contribution guidelines](Contributing.md) for full details.
+
+## Set up a Local GitHub Repository
+
+- Clone the [gist GitHub repository](https://github.com/semanticarts/gist.git).
+- Run the script `./tools/setup.cmd`.
+- Check to make sure that `./tools/pre-commit` has been copied to `./.git/hooks` and is executable. This ensures, among other things, that the serializer `./tools/serializer/rdf-toolkit.jar` runs before each commit. The serializer converts files into a standard Turtle format in order to remove noise in the diffs. No ontology files should be committed to the repository without running the serializer.
+
+## Create a Working Branch
+
+- Create a working branch from the base (target) branch. This is typically `develop`, but there may be a release branch.
+- Name the branch with your username + slash + issue number + brief description. Example: `jsmith/546_documentation_updates`.
+
+## Implement
+
+- Change the status of the issue you are working on to "In Progress."
+- Work on one issue at a time unless they are closely interconnected.
+- Consult the [_gist Style Guide_](gistStyleGuide.md) to ensure you are following gist conventions and best practices during implementation.
+- The serializer `./tools/serializer/rdf-toolkit.jar` *must* be run before every commit. If you have followed the [repository setup instructions](#set-up-a-local-github-repository), this will occur automatically.
+- Add a release note as described in [_Contributing_](Contributing.md#release-notes).
+
+## Submit a Pull Request
+
+- When implementation is complete, [create a pull request](https://github.com/semanticarts/gist/pulls) to the base branch.
+- Add the text "Closes #nnn" (where nnn is the issue number) to the description field. (If there are multiple issues, you must use the keyword "Closes" before each one.)
+- Assign the PR to yourself.
+- Add the PR to the same project as the issue. Set its status to "In Review."
+- Set the issue status to "In Review."
+- Submit the PR.
+- Resolve any conflicts with the base branch.
+- Assign one or more reviewers.
+- Address reviewer comments.
+- For straightforward changes, resolve the comment when fixed.
+- Re-request reviews.

docs/ContributorQuickReference.md

@@ -8,7 +8,7 @@ the release package will include queries to facilitate the migration of existing
 
 For changes that are not amenable to automatic migration, queries will be provided that
 report the use of deleted or modified classes and properties so that mitigation measures
-can be initiated.
+can be initiated. For example, some releases may require manual intervention when a property is being replaced by its inverse (in class expressions, restrictions, and definitions of subproperties).
 
 Every major version of `gist` (starting with 10.0.0) will add a sub-directory under the
 `migration` directory containing the queries and two migration scripts:

docs/MajorVersionMigration.md

@@ -0,0 +1,21 @@
+# Guidelines for PR Reviewers
+
+- PR reviewers should ensure that the guidelines for submitting a PR have been followed; see [guidelines for submitting a PR in _Contributing_](./Contributing.md#submitting-a-pull-request-pr).
+- If any of the following problems exist, the reviewer may opt to fix them or return the PR to the author:
+  - The PR has not been assigned to the same project as the issue being addressed.
+  - The PR and the issue have not been assigned status "In Review."
+  - The description does not list the issues closed by the PR, using the phrase "Closes #nnn" where nnn is the issue number. If more than one issue is closed, each should appear on a separate line preceded by the word "Closes."
+  - The PR is not submitted to the appropriate branch (usually `develop`, but in some cases there may be a release branch).
+- The PR should be returned to the author for any of the following problems:
+  - There is no release note or explanation in the PR description of why none has been included.
+  - The release note does not adequately reflect the contents of the PR or does not conform to the [guidelines](./Contributing.md#release-notes)
+  - The serializer has not been run or the diffs are noisy for some other reason.
+  - The changes do not conform to the agreed upon implementation described at the bottom of the issue.
+  - The ontology is not logically consistent.
+  - There are conflicts with the base (target) branch.
+  - Some checks have not passed.
+  - The changes included in the PR are not all within the scope of the issue.
+- Commenting on the PR:
+  - Review the [GitHub documentation on commenting on PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) for general information.
+  - Do _not_ commit your suggestions to the PR itself. Enter comments in the comment box for the author to review.
+  - It is helpful to enter minor suggestions such as small wording changes as GitHub suggestions, allowing the author to accept and commit the suggestion with a button click. You can do this by clicking on the small +- icon to the right of the word "Preview" in the comment box. See [item 7 in the GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-comments-to-a-pull-request).