ID management in Uberon¶
Temporary IDs¶
“Temporary IDs” are an experimental mechanism to allow editors to mint new term IDs without worrying about potential conflicting IDs.
This is primarily intended for AI agents, which are likely to open many PRs in parallel but have to share a single ID range (contrary to human editors, who all have their own range) and have no way of keeping track of which IDs are being used in concurrent PRs (again contrary to human editors, who can rely on Protégé for that).
However temporary IDs are in no way restricted to AI agents, and any editor could use them if they so want. For example, they could be useful for an external, occasional editor – someone who is not a known contributor to Uberon and for whom we may not necessarily want to allocate a dedicated ID range.
Editing the ontology with temporary IDs¶
From an editor’s point of view, all that is needed to use temporary IDs
is to use the Temporary IDs
range defined in the uberon-idranges.owl
file.
For editors using Protégé, this means selecting said Temporary IDs
range when Protégé asks you to select an ID range policy, just after
having opened the Uberon edit file.
For other editors (including AI agents), this means making sure that
whenever a new ID is needed, it is generated within the range allocated
to Temporary IDs
(it should normally be UBERON:99NNNNN
, but please
check the contents of the uberon-idranges.owl
file, just in case the
range is changed in the future).
Replacing temporary IDs with definitive IDs¶
Replacing temporary IDs with definitive IDs is done by invoking the
allocate-definitive-ids
target:
This will find all temporary IDs within the ontology and replace them
with newly allocated definitive IDs picked from within the Automation
range defined in the uberon-idranges.owl
file. All axioms that were
referring to temporary IDs will be automatically re-written so that they
refer to the corresponding newly allocated definitive IDs.
This replacement must be performed at the latest possible stage, just before a PR is merged. If temporary IDs in a PR are replaced by definitive IDs, and the PR is then left unmerged for a while, then ID conflicts may occur when the PR is finally merged.
For convenience, a GitHub Actions workflow is available to perform the
ID replacement step on a PR without requiring a Uberon maintainer to
check out the PR and invoke the allocate-definitive-ids
manually. When
a PR containing temporary IDs has been deemed OK for merging, a
maintainer should trigger the allocate-definitive-ids
GitHub Actions
workflow on the PR’s branch, wait for that workflow to terminate (it
should take a couple of minutes at most), and then immediately merge
the PR.
Automatic replacement of temporary IDs upon pushing to master¶
Alternatively, a PR containing temporary IDs can be merged “as is” to
the master branch. This will then trigger an automatic ID replacement
operation (made by the same allocate-definitive-ids
GitHub Actions
workflow), directly on the master branch.
Compared to the approach above, where the ID replacement is done on the PR prior to merging, this approach has the following advantages:
- it is entirely automated, and does not require any manual intervention from a maintainer;
- it eliminates the risk of an ID conflict still occurring between the moment IDs are replaced on a PR and the moment the PR is merged.
It has the inconvenient that it lets temporary IDs becoming part of the history of the master branch, which may make perusing the history more cumbersome as the history will be “polluted” by commits that do nothing more than rewriting IDs. With the “replace-before-merging” approach, such commits can be made invisible if the PR is small enough to allow for a “squash merge” instead of a normal merge – then only the definitive IDs will only ever make it to the master branch.