toc

toc copied to clipboard

Ref:

1. https://github.com/cncf/toc/pull/868#issuecomment-1216780714
2. https://cloud-native.slack.com/archives/C0MP69YF4/p1664877614078159
3. https://cloud-native.slack.com/archives/C0MP69YF4/p1665262092502759?thread_ts=1665101308.201549&cid=C0MP69YF4

What this PR does:

• This PR treats a tags.yaml file as the source of truth for all metadata related to TAGs and WGs. This is heavily inspired from the Kubernetes community.
• The code also "implements" https://github.com/cncf/toc/pull/868 and requires WGs to be part of a TAG. I couldn't find all WGs to be well-documented so I've only added a working group for TAG Contributor Strategy as an example.
• The following file structure is generated in the tags directory:

.
├── chair-transition.md
├── cncf-tags.md
├── generator    -> contains code for generation
├── go.mod
├── go.sum
├── liaisons.md. -> mapping of TAGs to TOC liaisons
├── Makefile
├── proposed.md
├── README.md
├── tag-app-delivery -> each TAG has a directory
│   ├── charter.md
│   └── README.md   -> README of each TAG contains info about leads, meetings, slack channels, etc
├── tag-contributor-strategy
├── tag-environmental-sustainability
├── tag-list.md     -> Overview of all TAGs and their corresponding WGs
├── tag-network
├── tag-observability
├── tag-runtime
├── tag-security
├── tag-storage
└── tags.yaml       -> machine-readable source of truth

This is WIP because:

• [ ] Need to write docs
• [ ] Need to set up CI

Structure of commits:

• The 1st commit adds code for generating docs from tags.yaml.
• The 2nd commit adds the tags.yaml file.
• The 3rd commit adds all files generated from the above tags.yaml file.
• The 4th commit finally moves all charter docs to the respective TAG directories.

@amye I haven't forgotten about your request for documenting when a lead was added. However, that's a bit involved and I'd like to do that as a follow-up :)

@nikhita could you take a look at this PR and see if it is still needed (I believe it is - its just been a while)? if so, would you update it to resolve the conflicts?

Hi @nikhita, I met up with @jeefy to go over this to see how we can help out.

We could make two GitHub Actions ...

1. The first action prevents manual/ad-hoc changes to generated markdown files, signposting the need to only update tags.yaml
2. tags.yaml changes run your code in an action and add the generated MD files to the PR, thus preventing the need to run make generate locally

Let me know what you think, talk tomorrow!

@nikhita @jeefy @RobertKielty wanted to check in on this - what else is needed to move this forward? looks like a decision was needed

@nikhita I am busy looking at all the open issues and PRs in the TOC repo.

From what I can work out, the aim of this PR overlap with the work I presented at the TOC/TAG meeting in Paris.

Out of the Paris proposal we created a README and Chart template for TAGs to use in updating their documents ensuring that only one copy of their charter exist in the TOC repo and only one copy of the README in the TAG's own repo.

This PR generate README for each TAG in the TOC repo. What was your thoughts around the README in each TAG's own repo? Should it be a copy of the one generated here? or deleted and only live in the TOC repo, hyperlinked to the TAG repo?

From my proposal the leadership should only be listed in the toc/tags/cncf-tags.md and hyperlinked back to the TAG repos to ensure only one list of leadership should be kept up to date. It is manual and not a .yaml file, but the info live only in one place after updating the charters and READMEs.

The other "source of truth" for TAG leadership, but more related to repo access is in the cncf/people/config.yml file, so if we make sure that is 100% accurately reflecting TAG leadership we could even pull the "truth" from there? That is if we move forward with this PR- (From a TAGs point of view the file need a good review)

@nikhita what is your thoughts? Should we revisit this PR, updated it to where needed to let it merge? Or go with the "not so automated" ideas from Paris?