Time

Agenda Item

Lead

Notes

3 min

• Start recording

• Welcome & antitrust notice

• Introduction of new members

• Agenda review

Chairs

• Antitrust Policy Notice: Attendees are reminded to adhere to the meeting agenda and not participate in activities prohibited under antitrust and competition laws. Only members of ToIP who have signed the necessary agreements are permitted to participate in this activity beyond an observer role.

• New Members:

5 min

General announcements

All

Any news and updates of general interest to CTWG members:

5 min

Review of previous action items

ACTION: @Judith Fleenor (Deactivated) to review the Archived Landing page of Concepts & Terminology Working Group. 

5 min

Version management of Spec-up vs. version management of terminology

@Henk van Cann 

This was an experiment to see if copies or branches will maintain version history. The experiment showed that in git:

1. A copy will NOT preserve version history.

2. A overwrite of a file WILL preserve version history.

3. Version history will be preserved over branches.

Our conclusion: we want to preserve version history, so we should be use git overwrites.

The next step is to prove that we can observe the history of any term definition.

10 min

Terminology Governance Guide

@Henk van Cann

Every meeting a new aspect to discuss and decide upon. https://trustoverip.github.io/ctwg-terminology-governance-guide/

We skipped this topic today.

5 min

Spec-Up Use

@Darrell O'Donnell

 @Neil Thomson @Drummond Reed  

Spec-Up tips & tricks As we have many specifications in flight I have been compiling some SpecUp tips & tricks

@Neil Thomson suggested that he could document how to set up locally from a clean slate vs. a user who already has GitHub set up locally.

20 min

ToIP Glossary & Spec-Up Proposal

@Drummond Reed 

Drummond posted the following proposal to Slack:

Having started working with Spec-Up directly (to convert the ToIP Technology Architecture Specification into Spec-Up), I had a quick discussion with @Darrell O'Donnell (who is also now a regular Spec-Up user), and I have a new proposal for how to at least initially solve our “versioned links” challenge. This solution is premised on a key constraint of Spec-Up xrefs: every xref must reference a specific Spec-Up file containing the target term and definition.Given this constraint—plus the fact that as glossaries mature, they tend to evolve relatively slowly—my proposal is to combine several of our previous proposals as follows:

1. Establish a single current version of the ToIP Glossary at a ToIP permalink which any ToIP (or other) Spec-Up document can reference with an xref tag (by putting that permalink URL in the spec’s xref tag list) if what the author wants is a reference to the current definition of a term. (This permalink would not contain a version ID).

2. Generate that current ToIP Glossary generated from individual GitHub Markdown files for each term as proposed by @Henk van Cann and @Kor Dwarshuis.

3. Periodically—I propose every calendar quarter (but only if there have been changes) — save a snapshot of the ToIP Glossary as a complete Spec-Up document at a ToIP permalink for that version. This permalink would include a version ID in the URL (either a sequential version integer, e.g., v3, or a year-month stamp, e.g., 2024-07). This way any author that wants to link to a specific version of a ToIP Glossary can do so just by including that specific ToIP permalink in their Spec-Up xref file list.

This seems like a practical solution that will meet all our requirements, i.e., individual terms can be edited independently via GitHub, and then full ToIP Glossary versions can be generated, but only quarterly (and even then, only if needed). We can maintain a CTWG wiki page with the permalinks to each published version. Even in 10 years (by which time things would have almost certainly have evolved), it would only have a maximum of 40 links on the list.

@Rieks Joosten replied:

 I second this proposal. It may be worth considering to have the individual files comply with the TEv2 specifications for curated texts. From that, it would be easy to create a Spec-Up to create an updated version of the ToIP Glossary as Drummond proposes in his point 1. And it would simultaneously pave the way for those wanting to use the TEv2 toolsuite, e.g., to refer to terms in the TEv2-way, or to generate all sorts of human-readable glossaries. That is because I think that a ToIP Glossary as Drummond proposes is the Spec-Up simile of the TEv2 machine-readable glossary, which would then be generatable from the TEv2 tools.

@Henk van Cann replied:

 I support the approach as long as we try to:

1. avoid copying full files of terms but instead let git *versioning* do the job

2. automate creation, maintenance and reference of specific versions whenever we can

3. keep a complete git history, consistently available, of each spec-up repo involved in any combination of def, ref and xref usage.

The reason I'd like to stick to these constraints is:

1. a single point of definition and reference

2. consistency

3. to avoid manual labour (for example on dead links).

At least for the time being I'd also like to focus on implementing [Drummond's point 3](https://trustoverip.slack.com/archives/C01BBNGRPUH/p1716356848969529) with my constraints above. I'm convinced it's possible to offer functionality that creates and manages snapshots with git and github and at the same time avoids "hell", as Darrell described it a few weeks ago.

Drummond's Point 2 is not Kor's design - nor mine; that'd be too much honour. One term per file stems from TEv1, Wiki-based term defs, and TEv2. The Spec-Up based ToIP main glossary took a different turn: one file, many terms. We now only try to bring the one-term-per-file principle back in Spec-Up-based source management of term defs and (x)refs, plus the consecutive generation of specification documents, glossaries and dictionaries. The fundamental building block associated with this is "one term per file" with an unbroken strain of commit hashes all the way back through its relevant history.
If things are easier than I think and more production-ready than I know, I would welcome Pull Requests that tap into those available resources straight away.

The discussion at the meeting was generally in favor of this proposal, however @Henk van Cann suggested that there were several options that should be explored for NOT having to copy any of the ToIP Glossary term files into periodic versions as Drummond had suggested. Instead, such versions could be generated dynamically by code operating against GitHub.

Drummond liked that idea if it was technically feasible. So we concluded with two action items:

ACTION: @Drummond Reed to write up the proposed requirements to support permalinks to the ToIP Glossary that enable document authors to link to either: a) the current version of a term, or b) a specific version by either datetime tag or explicit GitHub version tag.

ACTION: @Henk van Cann and @Kor Dwarshuis to explore the options for implementing in GitHub the functionality necessary to meet the ToIP Glossary permalink requirements.

5 min

ToIP Glossary Open Items

@Drummond Reed 

Drummond shared that this week, he plans to start making edits to the ToIP Glossary Spec-Up file, including cleaning up the structure.

ACTION: @Drummond Reed to report out in the next meeting on his progress and any issues encountered with editing the ToIP Glossary Spec-Up file.

2 mins

• Review decisions/action items

• Planning for next meeting 

Chairs