Versioning of terms - Henk van Cann - september 2022

@henkvancann created this issue in the essif-lab repo. Since the TEv2 tools and docs have been transferred to this repo, we keep this issue here, and we closed the one in the essif-lab repo. Here is the original text of the issue (without the comment of @sih that basically was agreeing with the approach that @dhh1128 proposed):

Henk van Cann:

10:28 AM Daniel, I have a question about keeping in sync with changes to the ToIP glossary. I store terms under their name (e.g. ‘issuance-event’) in one central database, where I intend to generate a documentation site and sidebar menus from. I have attached a unique identifier to a term (not yet used by the way). A key situation would be the change of the name of term. My question is this one: could I get a periodic update of ToIP terms (acdc, but also the other ToIP glossary wikis) that have changed the name (old name-new name) of the term, because those ones are going to be dead links if I don’t regularly process them at my receiving end. Example : ‘issuance-event’ changes for some reason not relevant to ‘issuer-event’. Proposed follow-up: Github Actions “knows” this and reports in intervals (once per week, per month) to those e-mail addresses that have subscribed. If an editor of a glossary changes the name of term (but keeps the concept/explanation more or less the same), then he / she should alter the text of the old term in a way that is backward compatible, either: a) the old term gets a new meaning plus a forwarder to new name (with the old concept text). b) the old term gets a forwarder (old name url -> new name url) which becomes obsolete over time (edited) white_check_mark eyes raised_hands

Daniel Hardman 10:42 AM Each repo keeps a record of github actions that it run, so you can see whether/when the glossary has been regenerated by looking at that log: https://github.com/trustoverip/acdc/actions Even better is to use the github compare function. Here is a URL that shows everything that has changed in the glossary in the past 7 days: trustoverip/acdc@gh_pages@{7day}...gh_pages You can change the "7day" part to get other durations. Does this accomplish what you want? 10:44 Here is more info about how to use the compare function: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits

Henk van Cann 10:44 AM I’ll check it out, sounds good. However, I am more concerned about the human intervention (the governance aspect) Idealistic someone (including myself!) who changes names has a sort of a duty? Example a) issuance-event

Definition

Former Concept Issuer-event Example b)

Daniel Hardman 10:46 AM I see. Yes, that's a bit different. Yes, right now the plan is that this is the job of the human curator. Adding a feature to a github action to do it automatically would be cool, but it's not something I can work on at the present.

Henk van Cann 10:48 AM I need to study Github Actions more (but also focussed on other stuff). It’s good to sync about this very specific situation, It happens quite often in the keri team: acronyms and names change. 10:49 we need to keep track in some way

Daniel Hardman 10:50 AM I think that instead of renaming something, we should deprecate the old thing and then add a new thing, and cross-link them (so that the old term is still searchable, but is marked as deprecated, and so the new term contains a note that it has replaced the old term). This is typically how professional terminologists do it. (edited)

Henk van Cann 10:50 AM that sounds great, yes better than my approach 10:51 This however, works only if the old name does not get a new meaning 10:52 But anyways, let’s say, it’s on our agenda :) 👍

tno-terminology-design / tev2-specifications

Versioning of terms - Henk van Cann - september 2022 #2

Definition

Former Concept Issuer-event Example b)