As part of the review of TAG repos, as well as cncf/toc/tag folder I found that information like the TAG charters and leadership is documented in various locations and the information is often miss match between documents.
What problems are we solving?
This issue list a few problem statements and actions that would help simply the workflow for keeping TAG information current and provide a better repo end users experience.
The current README file in the cncf/toc/tag folder is a list of TAGs, their TOC reps and TAG leadership. The tag leadership heading state that the leadership list was last updated March 2022. Changes have however been made to the leadership list after March 2022, making the date invalid. Comparing this list to the TAG repos there are also some leadership information mismatches.
In the cncf/toc/tag folder there is a file "cncf-tags.md" that gives a good overview of "what is a tag and how it should work". This document also seem a little dated and could do with some updating. (For the moment I aim to organize the folder and not update the document, we will get to that in a next step) In my opinion the README of the TAG folder should be an explanation of "what is a tag and how should it work", and out of that it should link to a list of TAGs within the CNCF containing essentially the information that is in the current README.
The tag folder contain a sub-folder for "resources", however there are "resources-type files" in the tag folder. ie. chair-transition.md which would be more at home in the "resource folder". Aiming to move those as well.
Taking Action
A pull request would be created that would address the following:
[x] Rename the file "cncf-tag.md" to be the README for the repo
[x] Add a section to the updated README that would hyperlink to a file named "cncf-tags.md" containing information about the TAGs. (the content of the current README, but updated)
[x] Update the "cncf-tag.md" file to list TAGs with a hyperlinks to their respective repos, listing TOC liasons per TAG, TAG Leadership (both chairs and tech leads) - this would start with the content of the current README, but would be expanded and updated with leadership information form the TAG repos, fixing out dated leadership listings, rearranging it all in alphabetical order.
[x] This feed into a strategy for reducing the complexity of updating TAG documentation - More about this below.
[x] Move "resource" files into the "resources" sub folder. There are several PR's in flight that add more resources and update the current resources files. - As those PRs land we could further evaluate the folders and sub-folders of the "resources" folder.
Flow-up strategy:
This issue would is the starting point for a strategy to reduce that burden on TAGs for keeping their information updated "in all the places"
Some of the next steps
Charters and README files:
There are charter files for each TAG in the cncf/toc/tag folder.
The TAGs also have a charter file in their own cncf/tag-foo-repo.
Glancing through the various copies of charters across repos, there are substantial mismatches in the content of these charters as well as the projects listed in those charters.
A follow up issue would be opened to support TAGs to update their repo README and charters, remove similar information across repos, using links across repos instead of duplicate information that age badly.
Rather than listing projects manually we would advocate the use of live links to CNCF/Landscape2, which now support filtering of project by TAGs (still some issues with those links, but they are on their way!)
The proposed README and charter review also align with discussions in the Dec 19, 2023 TOC meeting where a review of all TAG's charter where discussed. - a great project for 2024.
As part of the review of TAG repos, as well as
cncf/toc/tagfolder I found that information like the TAG charters and leadership is documented in various locations and the information is often miss match between documents.What problems are we solving?
This issue list a few problem statements and actions that would help simply the workflow for keeping TAG information current and provide a better repo end users experience.
The current README file in the
cncf/toc/tagfolder is a list of TAGs, their TOC reps and TAG leadership. The tag leadership heading state that the leadership list was last updated March 2022. Changes have however been made to the leadership list after March 2022, making the date invalid. Comparing this list to the TAG repos there are also some leadership information mismatches.In the
cncf/toc/tagfolder there is a file "cncf-tags.md" that gives a good overview of "what is a tag and how it should work". This document also seem a little dated and could do with some updating. (For the moment I aim to organize the folder and not update the document, we will get to that in a next step) In my opinion the README of the TAG folder should be an explanation of "what is a tag and how should it work", and out of that it should link to a list of TAGs within the CNCF containing essentially the information that is in the current README.The tag folder contain a sub-folder for "resources", however there are "resources-type files" in the tag folder. ie. chair-transition.md which would be more at home in the "resource folder". Aiming to move those as well.
Taking Action
A pull request would be created that would address the following:
Flow-up strategy:
This issue would is the starting point for a strategy to reduce that burden on TAGs for keeping their information updated "in all the places"
Some of the next steps
cncf/toc/tagfolder.cncf/tag-foo-repo. Glancing through the various copies of charters across repos, there are substantial mismatches in the content of these charters as well as the projects listed in those charters.A follow up issue would be opened to support TAGs to update their repo README and charters, remove similar information across repos, using links across repos instead of duplicate information that age badly. Rather than listing projects manually we would advocate the use of live links to CNCF/Landscape2, which now support filtering of project by TAGs (still some issues with those links, but they are on their way!)
The proposed README and charter review also align with discussions in the Dec 19, 2023 TOC meeting where a review of all TAG's charter where discussed. - a great project for 2024.