# What a date can do

By: Kor Dwarshuis & Henk van Cann
Input: Drummond's external link versioning design in [Slack](https://wiki.trustoverip.org/display/HOME/Permalinks+to+the+ToIP+Glossary)

{ action items between curly brackets }

*Mind you: this design is **not** about a full version of glossary at a certain commit / tag. That's a separate feature.*

## Video recording

Explanation of the design in this [20 minute video](https://us02web.zoom.us/rec/share/FMiUKdPD5Lw28lRuCa589AxUNl1twRfFEMSh8jwhvwit2vITwPdNirG9SjHl88pl.AYnI1VthjYoxEwIQ)

Passcode: ^1EMx6B2

## For those who want to only quickly scan

The text and diagram below is explained in the video above.

### Pre-conditions:
- commit hashes are the way to go with date+time and curation in one go
- Good governance of destination terminology repo: unbroken chain of commits
- User rights well maintained
- No Wiki-based source management of terms

### Situation:
Each spec-up repo that use 1 or more xrefs has one or more related “xdoc”s mentioned in its specs.json

### Action:
Create or update an xref

### Challenge:
How to know which version of this externally referenced glossary was seen plus referenced by the author?

### Solution:
Versioning using git and observing via GitHub and front-end spec-up generated glossary/dictionary in the specification.

### How to:
So there are two ways to reference to a specific VERSION of a particular term in a particular xdoc:
1. We reference the latest commit hash of the whole external glossary at the time of the reference of one or more specific terms in this external glossary. {@Kor: is there really no way a directory can have a commit hash? ANSWER: only with the rarely used .keepgit placeholder file; see [explanation](https://chatgpt.com/share/9681cee5-acd6-4987-b079-2fd6bba5f1dd) }
2. We reference the latest commit hash of the referenced term at the time of the reference of this specific term in this external glossary.

The commit hashes of 1 and 2 might be different but are one-on-one related. With commit hash of 1 you can find commit hash 2 and vice versa. {We have to test this; UPDATE: not relevant anymore, option 2 is the way to go}

### Steps:
Save an xref -> commit hash source c#s -> date/time "dt" -> filter target repo with dt to get last commit hash destination c#d -> store commit hash c#d in specs.json

flowchart TD
%% Henk van Cann, Feb 15th 2024
  A["create xref ⛓️"];B[IDE tool];C["lookup 👁️"];D["commit 💻"];
  E["specs.json 🙈"]; F["specification with xref 👁️"]; G["lookup 👁️"]; H["config: latest/original 📝"]
  I["URL 📩"]; K["Term definition"]; L["lookup to compare 👁️"]
  M["Github DIFF in red&green"]
subgraph one[Use case A: Save xref]
    A -.-> B & C & D
    B --> |"consistent"|E
    C & D --> |"versioned"|E
    E --> |generate| F
    end
    one -.-> G
    one -.-> H
subgraph muliple[History and differences of ONE term]
  subgraph two[Use case B: Observe externally]
    H --> |choice|G
    H --> |choice|I
    G & I --> K

    end
  subgraph three[Use case C: Diff tool ONE term externally]
    L --> |create URL|M 
    K --> |create Github request|L
    end
    two-->three
end

## Use case {ABC below}: action -> result

### A. Save xref
In source management tool use Brian’s extension to consistently create an xref, {use the c#d look-up tool to be made}, save the file, stage & commit the change -> c#d in specs.json in xdoc structure

{xdoc url} {
{term}/{commit hash c#d?}
{term}/{commit hash c#d1}
{term}/{commit hash c#d?}
}

### Real world example
This is a fictional part of specs.json {ask Brian for this extension to his tool}:

"external_specs": [
{
"TG": "https://github.com/trustoverip/ctwg-main-glossary/tree/main/spec",
"terms": [
{
"name": "term1",
"commit_hash": "77cad15"
},
{
"name": "term2",
"commit_hash": "cd1892f"
},
{
"name": "term3",
"commit_hash": "ced49a6"
}
]
}
],
Term 1,2 and 3 have been used by authors in xrefs, the commit hashes are commits in the external glossary 'TG'.

## B. Observe version
Choose ‘latest’ or ‘original’, if latest then {use the c#L look-up tool to be made} else get the c#d from specs.json. get info via URL {https to glossary}/{anchor to term}/{commit hash c#d} -> (pop-up of) glossary definition text

Example:https://trustoverip.github.io/glossary/#term/282fa9

### Real world example
Observe commit b778be0024d4a0c2874e9aa882271fe38571220a of terms_and_definitions.md:

https://github.com/trustoverip/ctwg-main-glossary/blob/b778be0024d4a0c2874e9aa882271fe38571220a/spec/terms_and_definitions.md

Observe commit 2d52103467632d6afffa29dfdc6b8150a74d7334 of terms_and_definitions.md:
https://github.com/trustoverip/ctwg-main-glossary/blob/2d52103467632d6afffa29dfdc6b8150a74d7334/spec/terms_and_definitions.md

## C. Diff version referenced and latest
{Use the c#L look-up tool to be made} and get the c#d from specs.json
{https to GitHub diff tool}/{url on xdoc repo to term}/{commit hash c#d}+{url on xdoc repo to term}/{commit hash c#L} -> red and green differences visible in GitHub userinterface.

Example "diff":

### Real world example

Diff two commits. Now I can extract the commit hashes and say:
https://github.com/trustoverip/ctwg-main-glossary/compare/b778be0024d4a0c2874e9aa882271fe38571220a..2d52103467632d6afffa29dfdc6b8150a74d7334

However, you have to Command-F a certain file e.g. `specs.json` in the list or scroll down.

The following command will give the results for only the file `specs.json`. The github userinterface doesn't have this option (yet). So we're able to use this in an automated process.

> git diff b778be0024d4a0c2874e9aa882271fe38571220a 2d52103467632d6afffa29dfdc6b8150a74d7334 -- specs.json

If you find the web interface cumbersome for this purpose, consider using local tools like git or graphical interfaces like GitKraken, SourceTree, or GitHub Desktop.
These tools can provide a more user-friendly way to view diffs for specific files; try this for example:

git diff b778be0024d4a0c2874e9aa882271fe38571220a 2d52103467632d6afffa29dfdc6b8150a74d7334 -- specs.json