-
Notifications
You must be signed in to change notification settings - Fork 17
Workflow
In various aspects of maintaining an ontology, especially in the realm of developing for an ontology, there is a significant learning curve. In efforts to provide some guidelines, some common workflows are described.
Github is the central online hub to managing the Agronomy Ontology. All the modifications done by a curator or developer have to be uploaded to the AgrO repository. It is through github that a majority of users access AgrO and thus, keeping it updated is critical to its use. It is also through this repo that we communicate openly with any users, and track the requests and issues that face them.
In order to track the issues by users or start any update (minor/major), an issue has to be made on the repo's Issue Tracker. Here, we have templates to gather as much information as we can in an easy to enter page.
From the curator's perspective, the first step has to be to collect the open issues relevant to their work. There are three sources for issues:
- AgrO
- Other ontologies (ENVO, UO, ChEBI, etc)
- Private projects
The AgrO issues are public requests which can be made through anyone, including the curators to manage/track changes and hold discussions. This is the most often used issue source, followed by issues originating from other ontologies. Being part of a larger community, AgrO has extensive interoperatability with ontologies from which classes are imported and exported. The issues that arise as part of this interoperatability include term import/export requests, adding terms which may fit better in that ontology. The private project issues are usually bulk class imports where private groups request the addition of a list of terms to AgrO. These requests are generally submitted via the Ontology coordinator or via email. The reason for adding terms from private collections is so a permanent link and definition can be generated, which is especially relevant for publications. These bulk imports also help to define a functional model of Agronomy, which is critical to broader interpretations from practical data from around the world.
As is relevant from the perspective of general users, creating an issue for the first time is daunting and confusing. This hesitation can be addressed by maintainers providing templates for potential actions, where users can provide the required information per that action.
Generally, the templates are divided into:
- New Term Requests (NTR)
- Term annotations/axiom change
- Terms merge/obsoletion/import
- Errors/custom/development issues
When faced with having to create multiple issues, a great tool to use is the 'Github-CSV-tool' to create a list of issues per a template csv table. This is a npm-based tool which little to no coding proficiency required (maybe except for a bit of console (bash/shell) entry).
- Install:
-
github-csv-tools (in shell/bash):
npm install -g github-csv-tools
- Create CSV with headers:
- *title
- *body
- labels
- assignees
- milestone
*Essential Information
A template is available here: Github-bulk-issues-template
Github's branches are critical to maintaining controllable changes, in the event where some updates cause errors down the line, even if not obvious immediately.
It is highly recommended that each issue has it's own branch, to however many sub-branches or commits it may involve. For those unfamiliar with Git, any user can 'fork' a repository, which allows that user to modify any of the existing branches or create a new branch (for the purposes of merging into an existing branch) within the 'official' repository. Note that general users are not given access to edit through the AgriculturalSemantics group, but are encouraged to fork, clone, modify, commit and then create pull requests to add to the official AgrO repo.
For additional guidance on using Github and it's functionalities, there are a slew of tutorials online or simple guidance can be requested via the Issues tracker.
The release pipeline for the Agronomy Ontology follows merges into the 'master' branch, after running with the make 'release' recipe and creating a Github release. The release workflow can be found in the Tools>ROBOT>Releases section.
It is important to note that although the PURL links are created immediately, there is a delay to seeing a new term on the Ontobee site. This delay is due to the time-dependent checks performed by the publishing agent. It is expected to await 1-2 weeks for the latest changes to be found on the Ontobee site, however, the IRIs published in a release will always exist, and can be included in a publication immediately.