Require new ontologies' repositories to include documentation on how to contribute

[cthoyt]

I was just reading through the repository linked for PROCO in the new ontology request #1834, and it seems that the ontology has very little information on how the ontology is updated/maintained. Considering that many OBO Foundry ontologies suffer from issues related to longevity and sustainability, not having a document explaining how external contributors can make their own edits and send pull requests seems to be very counterproductive.

GitHub itself has a first-class notion of repositories including a contributions file. For example, in any repository, you can look at the "community page" e.g., https://github.com/proco-ontology/PROCO/community which links to this guide for writing contribution guidelines.

Some ways to make this actionable:

1. Add a new field to the metadata linking to the a contributing file (which should be in the root of the repository and can be a plain text file, a markdown file, or a restructured text file)
2. Update the new ontology request form to include a link to this file
3. Figure out how to check new ontology metadata files have this (but disregard old ones). While it's difficult to retroactively apply new rules, it's much easier now than it used to be to check repository properties en masse, as demonstrated in the OBO Community Health Report

[matentzn]

Awesome, didnt know about /community.

It may be next to impossible to get older ontologies to add contribution.md's but it reflects the principle of collaboration so concretely, that I would like to second @cthoyt motion to add that right to the principles. This is easy to be woven into dashboard as well.

[cthoyt]

I think it would a good idea to additionally write our own community guidelines on what a "good" contributing guide includes, and potentially include a few templates. For example, I think the ODK starter kit has quite a bit of this already baked in so this would apply to other repos not using this. Some things to consider:

1. Write out which ontology file is the "single source of truth" or "editable" file
2. Link to information on how to edit this file (e.g., OBO and OWL are edited pretty differently).
3. Are there specific rules/SOP/guidelines about what new terms will get considered for your ontology? Do you want people to submit issues, or edit the ontology and send a PR themselves?
4. Are there specific rules/SOP/guidelines about making edits to existing terms in your ontology?
5. What are your contribution attribution policies? Do people who submit issues for new terms get credited?
6. Is there CI that gets applied for QA checking on PRs? How should these results be interpreted? Do the maintainers participate actively in discussion to help people pass CI, or should they figure it out themselves before it gets considered?

[matentzn]

I think so too, very good idea! Whoever picks this up, just make a PR on https://github.com/INCATools/ontology-development-kit/blob/master/template/CONTRIBUTING.md.jinja2 and we will go from there! Thanks for the excellent suggestion.

[matentzn]

I will work on this slowly slowly: INCATools/ontology-development-kit#620

[matentzn]

@erik-whiting please make sure this is reflected in the "collaboration principle" page.

[nlharris]

@erik-whiting please make sure this is reflected in the "collaboration principle" page.

I worry that requests in already-closed issues may get lost. Should we open a new issue for this?