Style Guide

[neilotte]

We will be creating a style guide for the maintenance of CCO, which we can refer to for both quality control as well as guidance to developers. If anyone wants to contribute to this document, please feel free to place ideas or recommendations here.

@johnbeve @alanruttenberg @mark-jensen @APCox @cameronmore

[swartik]

The guide needs to describe the git workflow(s) used to maintain CCO.

[neilotte]

@johnbeve and @mark-jensen have been working on that for us and we will certainly be publishing this as soon as we are able.

[cameronmore]

Definition sources need some guidelines, in particular:

1. The priority and quality of sources. For example, should we prioritize a Merriam Webster source or Oxford English Dictionary Source? Or prefer sources from Standards documents, when relevant.
2. How to Cite Sources For online resources, a URI seems appropriate, but should we use dc terms bibliographic citation for articles and books? What citation style should we use? (APA or MLA is common, I personally prefer Chicago). Also, should the value of the annotation be, strictly a URI or citation or looser like "Adapted from [insert source]" or "Quotes from [insert source]". Or, a case by case basis.

[alanruttenberg]

Commit messages should mention the issue they address. E.g. see linking a pull request to an issue
But you can mention an issue in a commit message that doesn't necessarily close the issue using #<issue number>

[alanruttenberg]

If an issue is moved to a discussion (I've related to Neil Otte my concern that this isn't necessarily a good practice) please include the link to the discussion.

[neilotte]

Hi Alan, "please include the link to the discussion" where?

[neilotte]

Also, note that there are two ways to move something into discussion. First, you can re-create a discussion thread and cite tickets that have been closed and link to them; however, github encourages the full transfer of a thread directly into a discussion. One can do this by selecting the 'transfer to discussion' link which is the right of each issue. I think where the full thread is appropriate for continuing the discussion, the latter is preferred and I will lean towards this. The former is preferred where one wishes to consolidate an issue with the concensus of the respondents.

[alanruttenberg]

In the original issue(s).

[cameronmore]

A clear versioning policy should also be included--how to version the smaller modules and / or the larger combined file, and maybe some guidelines for 'when it makes sense to cut a release'? That might be too hard to quantify in detail.

[swartik]

When you talk about versioning the smaller modules and/or the combined file, are you referring to:

• The owl:versionInfo annotation?
• The ontology version IRI?
• A git tag?

Or something else?

[cameronmore]

all? and more? Don't need to be a super long part, but just part of the dev process that needs to be stated as part of a procedure