Several things missing from Contributing.md

[rivettp]

(The following are comments originally made on the Developer Guide in the wiki, revised to the new document)

• Need to tell people how to start with GitHub in term of the steps to fork to your own GitHub repo (with naming guidelines?) and then clone to a local copy for development (e.g. using SourceTree). I think we have steps documented for this. Should also refer to a generic (non-FIBO) GitHub 101 guide, and probably a Jenkins one. Also need to describe how to get updates (I prefer to pull them into my local clone then later push to my personal GitHub repo).

• Need to tell people to create (and how to name) branches based on issues, and to stick to one change per branch. And, for long-lived branches, how to merge in the latest changes from master. And how people should resolve conflicts. Speaking of which, should mention how we use master and that it contains all levels of maturity.

• Need to cover the whole pull request process i.e. Push to your fork on GitHub and then initiate the PR from there. And what needs to be done regarding the issue (e.g. referencing the issue number in the pull request comment as well as the branch name). Then what they can expect to happen from there.

• In terms of the development process I'm puzzled that it's buried in the Maturity Levels section and by the first bullet (changing Provisional to Release). a) because someone may be making a minor change not intending to promote the maturity level and b) from a process point of view do we want to allow anyone to do that?

• Need more background on catalog files and why we have catalog files in the source code tree. For About files, should tone down the explanation - it's not necessary to always load all files.

• Documentation of tooling, such as the pre-commit hook, should be done earlier than under Pull Requests. If people leave it until then it's too late since their prior commits will be based on unserialized diffs.

• Need more detail in Step 5 regarding "perform local tests". And the "Local testing tools" are barely testing tools at all, and certainly do not include "a variety of tests" aside from basic syntax checking. We should provide some expectations as to what sort of testing we expect, and also encourage/insist on documentation of what has been tested. Ideally we should have repeatable, if not automated, tests. We should provide guidance/tooling for developers to manage their test data (typically individuals)(nice if these were reusable) and scripts (e.g. SPARQL queries). Also possibly document availability of tooling such as Stardog.

• The most important test is to run a reasoner to check for inconsistencies. We should say/point to how to install the best (Pellet) in Protege (since it needs to be separately downloaded).

• Should be more specific about what it means for a fork to be "registered" and why that's important.

• We should also have more detail about the automated (hygiene and other?) tests (that people will hence not need to test for themselves), including how the results are reported and the difference between warnings (OK) and errors (not).

• Given that we have lower expectations for Provisional we should state that (presumably) not all tests need pass. We should provide guidance for people to document what has not passed (and hence requires further development work). Should people raise JIRA issues for such failed tests?

• Need to cover that any merged PR of an ontology that is Release maturity will be immediately published to Development, but not to Production until the next quarterly release. Assuming people agree to my proposal for a 4th ReleaseUpdate status that needs to be covered too. If we don't have that status, document how people know what's in Production or not.

• Should be clearer that the source is in RDF/XML (as opposed to other RDF syntaxes). And that the format is subtly different from the RDF/XML which is published (so people must not start from the latter when making a change).

• Due to the Serializer people should be warned not to spend time manually formatting the OWL.

• Also people should check the diffs associated with the PR to ensure the serializer made no unwanted changes

• Mention is made that the publishing process will rewrite URIs, but people should be guided on the URIs to be used in the source ontologies.

• There should be a single place (in this document or elsewhere) where we publish the versions of tools to use (and whether each version is recommended or required (e.g. CCM))

• say something regarding the issue we had with out-of-date versions of git within SourceTree and how to update that

• should cover how to synchronize a local branch with latest master. Including pros and cons of Pull vs Rebase. People are still scared/suspicious about this whole aspect that they will lose their changes

• I think we said we wanted people to suppress intermediate commits that go into a PR?

• Should cover process for making changes in response to PR comments; up to now we (me and Elisa Kendall) have been updating the PR by making further commits to their fork (as opposed to deleting the PR and making a new one)

• point out that there's a lag between a PR being merged and the result being published as Dev; and how people can check whether it has been

• people should update the status of the issue - including to In Progress when they create their branch, and check that it's been Closed once the PR has been merged