# Glossary maintenance at Trust-over-IP

## What are we talking about
- [Github Actions trustoverip pages-build-deployment](https://github.com/trustoverip/acdc/actions/workflows/pages/pages-build-deployment)
- [Github Actions trustoverip Update Glossary](https://github.com/trustoverip/acdc/actions/workflows/glossary.yml)

## Objective
A more sustainable github maintenance of the CDCI scripts (github actions) at Trust-over-IP.
This write-up intends to describe the full picture and see if we can anticipate on troubles instead of experiencing them.

## Reason
Why am writing this? I feel the issue of maintenance lagging behind holds me back a bit to spend time on the [ACDC glossary](https://github.com/trustoverip/acdc/wiki) at ToIP and we were thinking of a self-managed solution already, which of course is not good from an integration and standardization perspective.

How do we prevent people backing off because the automatic glossary generation fails?

## Proper governance
To enhance the GitHub Actions specific knowledge at ToIP to orderly maintain github actions we might want to document and maintain this in a team. Three things will have to be arranged for this:
1. user rights on the system
2. transfer to know what it is like now
3. budget

We preferably need a team so ToIP doesn't have to rely on individuals who leave a search trail as soon as they move on.

> In the first two points there's a *chicken-and-egg challenge*:
You get user rights with confidence in your ability and knwoledge about your character (cautious vs raucous). By the way, this can be solved by 'successfully completed training' certificate. Without user rights on the system, you have to work with your hands tied behind your back.

## The broader perspective
eSSIF-lab.org has a Docusaurus-based site. ToIP works together with eSSIF-lab on concepts and terminology and glossaries to:
- have their own interpretation of this need
- to integrate worldwide
- [Weboftrust](https://github.com/weboftrust) has a [Docusaurus-based site](https://weboftrust.github.io/WOT-terms) for their concepts, terms and education services. The glossary of the group that develops KERI, CESR and ACDC (and a few more) is input and hosted at ToIP wiki [here](https://github.com/trustoverip/acdc/wiki).
- Because *WebofTrust* uses ToIP wiki glossary we have two advantages:
- the ToIP glossary for ACDC is automatically generated in their domain [here](https://trustoverip.github.io/acdc/glossary.html).
- integration: we have exactly the **same glossary items** in [WebofTrust education site](https://weboftrust.github.io/WOT-terms/docs/terms/glossary/intro/?level=1). We manage to do this by harvesting: pulling the trustoverip wiki repo to a local machine and then add / overwrite this content (markdown files) to the Docusaurus document tree.

So there’s not only significant overlap in interests of ToIP and eSSIF-lab, but also between the projects under those umbrellas.

## Competences needed to manage integrated concepts, terms and glossaries
- General source code (version) management: git, github, NPM
- Workflow automation and CDCI: github actions
- Applied Cryptography: GPG/PGP (for the signing of PRs and commits), EasyCLA
- Specific for the technical documentation stack: Docusaurus, JSX/MDX, React, NodeJS,

## Direction of a solution
I would think of budgeting to start implementing 1. and 2. Immediately, retrospectively and then maintain them.
So both
- measurable and measured expertise in a number of areas before permissions are granted and
- continuous relentless documentation of how the system is set up and make that accessible. So that ToIP can handle in/out of co-workers.

What I am describing here has got attention already at ToIP, but we could do better, more accessible, spread across several people, more integrated with the Linux Foundation backbone.

## Transfer of know-how
Can be done well with proper documentation of what has been done in the past.

What we currently have:
- [How to Enable Glossary Generation for a Terms Wiki](https://docs.google.com/document/d/1g9H1voPijT4ZHQddPT873PIMSpkLzhZ_smJpndzUkLk/edit#)
- [How to Create Terms Wikis](https://wiki.trustoverip.org/pages/viewpage.action?pageId=76947)
- [Instructional video Daniel Hardman](https://www.youtube.com/watch?v=i-hK3pJxxUs) about How to Make a Terms Wiki

## Current affairs
How could we understand how things have been arranged so far. Answer to **questions** like these:
1. Are there any public documents how (we @ ToIP) select, test (and hire?) experts to do maintenance on github and document their work?
2. How is the CDCI environment designed, programmed and governed using git/github
3. Could anyone could point me to right resources to be able to master the procedures etched in `yaml` code?

### Answers
- The answer to (1) is *no*. Early on we had some ToIP volunteers who took on setting up our GitHub infrastructure. But then they moved jobs and left. So starting in 2021 we began relying on *Linux Foundation (LF)* staff for limited GitHub support (our direct Program Manager is not a GitHub expert but LF does have GitHub experts on staff they can consult).
- In January 2023 the CTWG did a bounty with an expert to develop the tooling (and documentation) we need for Terminology Engine V2, so he may have some of the answers you need for (2).
- See [Resources above](https://hackmd.io/pRuinoVJSZGT1xQT5ywIYA#Transfer-of-know-how). If not helpful enough, send a DM to @Michelle Janata and ask her who you can ask on the LF staff for help.

## Slack communication
Two channels are relevant: `#ctwg-toolkit-dev` and `#concepts-terminologie-wg`
- The operational part is more a topic for `#ctwg-toolkit-dev` channel
- CTWG has a steering role to lay out the roadmap and make things possible; milestones, competences, user rights, budget, etc ). We could discuss this in the `#concepts-terminologie-wg` channel

### Andor Kesselman of Linux foundation with tips

- [X] Question : Andor wrote “I had briefly looked into this a while ago, and remember coming across https://github.com/contributor-assistant/github-action. Has anyone tried this?”
Answer: Brian Richter had a look in the past.

- [X] Question: How does this relate to EasyCLA, because that’s what ToIP has adopted afaik.

#### Andor Kesselman - Mon March 26 2023
This is related to how to automate EasyCLA with github actions. From my understanding, this is used in quite a bit of repos in the Linux org, but they would be able to confirm:

### The failing script Slack thread

henkvancann
28 days ago
The github action to update the ToIP glossary fails consistently after I’ve done work on the acdc wiki. Here is an example:
”
build
Process completed with exit code 1.
build
Node.js 12 actions are deprecated. Please update the following actions to use Node.js 16: actions/checkout@v2, actions/setup-python@v2.2.2. For more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.
build
The `set-output` command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/
”
Who could have a look at this?
white_check_mark
eyes
raised_hands

21 replies

Drummond Reed
28 days ago
@henkvancann
This sounds like the EasyCLA problem. See if
@Brian Richter
can confirm that. He’s working with LF staff to try to fix it.

Brian Richter
28 days ago
yeah that is right this is the EasyCLA problem. Solution right now is to do the same process as the bot and push the glossary build with a github user account that has EasyCLA passed

henkvancann
28 days ago
This sounds like a two-step process then:
User account has access to the ToIP repo
User account has EasyCLA passed (whatever that means, have to look into it)

henkvancann
28 days ago
I am always suspicious when something starts with “Easy…” I’ve read it and watched a vid how to get an individual CLA, but where-o-where can I get one for the ToIP repos, easily :slightly_smiling_face: ?

Brian Richter
28 days ago
yeah so for step 2 the easiest way I know if is to create a PR and then it tells you the check has failed and how to sign the CLA... you're right it's far from easy

henkvancann
28 days ago
that’s a fair workaround, let me try this

henkvancann
28 days ago
Done. And then what would come next?
Screenshot 2023-02-07 at 22.29.18.png

Screenshot 2023-02-07 at 22.29.18.png

Brian Richter
28 days ago
looks like you are covered by easycla. now you just need to run the same code the bot does and create a pr to the gh_pages branch.heres the workflow it runs:
https://github.com/trustoverip/acdc/blob/main/.github/workflows/glossary.yml
basically just need to install the tt python program and then you can use it to generate the glossary
glossary.yml
name: Update glossary

'# Controls when the workflow will run
on:
gollum:
branches: [main]
'# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
inputs:
glossaryDefFile:
required: true
default: glossary.json
description: glossaryDefFile
deployBranch:
required: false
default: gh_pages
description: This is where the output of script will be pushed to.

jobs:
build:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2.2.2

- name: Install deps
run: |
git clone https://github.com/trustoverip/tt.git
python -m pip install marko
python -m pip install requests

- name: Set variables
env:
DEFAULT_GLOSSARY_DEF_FILE: glossary.json
DEFAULT_DEPLOY_BRANCH: gh_pages
run: |
echo "GLOSSARY_DEF_FILE=${{ github.event.inputs.glossaryDefFile || env.DEFAULT_GLOSSARY_DEF_FILE }}" >> $GITHUB_ENV
echo "DEPLOY_BRANCH=${{ github.event.inputs.deployBranch || env.DEFAULT_DEPLOY_BRANCH }}" >> $GITHUB_ENV

- name: Run script
run: ./tt/bin/tt glossary ${{ env.GLOSSARY_DEF_FILE }} >glossary.html.new

- name: Setup git config
run: |
git config user.name "GitHub Actions Bot"
git config user.email ""

- name: Publishing
run: |
git fetch origin
git checkout ${{ env.DEPLOY_BRANCH }}
mv glossary.html.new glossary.html
git add glossary.html
git commit -m "auto-update glossary"
git push
echo DONE

Show less
<https://github.com/trustoverip/acdc|trustoverip/acdc>trustoverip/acdc | Added by GitHub

henkvancann
41 minutes ago
Brian: “basically just need to install the tt python program and then you can use it to generate the glossary” -> I stopped here, because I did not get it.
Where should I install tt and which version.
(edited)

henkvancann
39 minutes ago
2. How should I use it to generate the glossary.
It seemed strange to me that I have to bypass the failing yml GH Action file by doing stuff by hand. (edited)

Brian Richter
36 minutes ago
you'll need to install tt in the environment you are trying to generate the glossary. so in this case if you are trying to bypass the failed action by doing it by hand you would need to have it installed locally.
yes it's strange but this is because easyCLA has prevented the bot from commiting the changes it needs to..

henkvancann
29 minutes ago
Ad 1. https://trustoverip.github.io/acdc/glossary.html is not under my control (I don’t have right to push there)

henkvancann
22 minutes ago
Maybe this section explains the context better to you: https://hackmd.io/pRuinoVJSZGT1xQT5ywIYA#The-broader-perspective

Brian Richter
21 minutes ago
403 on that page

henkvancann
17 minutes ago
sorry forgot to publish

henkvancann
16 minutes ago
now it’s readible?

Brian Richter
16 minutes ago
yes thanks

Brian Richter
12 minutes ago
ok I am still unsure of your goal. Are you a) looking to hire someone to figure out how to do this work now with the tools available? b) looking to get a glossary generated now? c) looking to get glossaries generating from now into the future?

henkvancann
7 minutes ago
You’re right, it’s mixed
a) no, I want to have the skills myself to do it
c) to fix the issues with the Github Action yml files structurally and set up a maintenance team within ToIP (if priority / urgency is felt)
b) is just a step for me to get a) and c) going

henkvancann
6 minutes ago
If I understand you well, I need user rights on ToIP repo to get b) going with tt.

henkvancann
3 minutes ago
Because this https://github.com/trustoverip/acdc/wiki I can edit and amend as a logged in github user, but to bypass the resulting* https://trustoverip.github.io/acdc/glossary.html I need user rights, for I am not allowed to push to ToIP yet.
*“resulting” because the failing workflow yml file normally would generate it for me (and for the other projects using the wiki-based gloss.) (edited)

Brian Richter
2 minute ago
I don't think many people have access to write to TOIP repos. I think the correct approach is to fork a repo, make the changes there and then send a pull request from your fork to the TOIP repo.

henkvancann
< 1 minute ago
Yes, besides trying to get the user rights, that’s the option I’ve got left. And exactly the reason why should have working workflow scripts in the first place, because PRs need human attention and follow up. :woozy_face:
Thank you for clearing things up. I now know how to approach this whole thing a-c. I’ll keep you updated! :+1: