What a date can do
By: Kor Dwarshuis & Henk van Cann
Input: Drummond's external link versioning design in Slack
{ 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
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:
- 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 }
- 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:
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
-
Any changes
Be notified of any changes
-
Mention me
Be notified of mention me
-
Unsubscribe
Subscribe