From 347f7d07d35979b952d52b1c4b234f3761dab2eb Mon Sep 17 00:00:00 2001 From: Nikhita Raghunath Date: Fri, 15 Mar 2019 16:33:11 +0530 Subject: [PATCH] generator: add support for committees Since committees can have private mailing lists, this commit also adds a new field for specifying private mailing lists in the "Contacts" section. --- generator/README.md | 24 +++++++++++--- generator/aliases.tmpl | 6 ++++ generator/app.go | 17 ++++++++-- generator/committee_readme.tmpl | 57 +++++++++++++++++++++++++++++++++ generator/list.tmpl | 7 ++++ hack/verify-generated-docs.sh | 2 +- 6 files changed, 105 insertions(+), 8 deletions(-) create mode 100644 generator/committee_readme.tmpl diff --git a/generator/README.md b/generator/README.md index 2c5ef157c..de68d18ee 100644 --- a/generator/README.md +++ b/generator/README.md @@ -1,7 +1,8 @@ # SIG Doc builder This folder contains scripts to automatically generate documentation about the -different Special Interest Groups (SIGs) and Working Groups (WGs) of Kubernetes. The authoritative +different Special Interest Groups (SIGs), Working Groups (WGs), +User Groups (UGs) and Committees of Kubernetes. The authoritative source for SIG information is the [`sigs.yaml`](/sigs.yaml) file in the project root. All updates must be done there. @@ -14,6 +15,7 @@ The documentation follows a template and uses the values from [`sigs.yaml`](/sig - SIG README: [`sig_readme.tmpl`](sig_readme.tmpl) - WG README: [`wg_readme.tmpl`](wg_readme.tmpl) - UG README: [`ug_readme.tmpl`](ug_readme.tmpl) +- Committee README: [`committee_readme.tmpl`](committee_readme.tmpl) **Time Zone gotcha**: Time zones make everything complicated. @@ -24,12 +26,13 @@ Practically, that means US pacific time must be `PT (Pacific Time)`. `PT` isn't good enough, unfortunately. When an update happens to the this file, the next step is to generate the -accompanying documentation. This takes the format of three types of doc files: +accompanying documentation. This takes the format of the following types of doc files: ``` sig-/README.md wg-/README.md ug-/README.md +committee-/README.md sig-list.md ``` @@ -64,9 +67,11 @@ make WHAT=container-identity where the `WHAT` var refers to the directory being built. -## Adding custom content to your README +## Adding custom content -If your SIG or WG wishes to add custom content, you can do so by placing it within +### README + +If your SIG, WG, UG or Committee wishes to add custom content, you can do so by placing it within the following code comments: ```markdown @@ -88,3 +93,14 @@ An example might be: - Do that ``` + +### OWNERS_ALIASES + +Similarly, custom aliases can be added in the `OWNERS_ALIASES` file by placing +it within the following code comments: + +```yaml +## BEGIN CUSTOM CONTENT + +## END CUSTOM CONTENT +``` diff --git a/generator/aliases.tmpl b/generator/aliases.tmpl index 313be36e8..52a7176e5 100644 --- a/generator/aliases.tmpl +++ b/generator/aliases.tmpl @@ -20,3 +20,9 @@ aliases: - {{.GitHub}} {{- end}} {{- end}} + {{- range .Committees}} + {{.Dir}}: + {{- range .Leadership.Chairs}} + - {{.GitHub}} + {{- end}} + {{- end}} diff --git a/generator/app.go b/generator/app.go index 0b17b100a..be33247f4 100644 --- a/generator/app.go +++ b/generator/app.go @@ -73,9 +73,10 @@ type Meeting struct { // Contact represents the various contact points for a group. type Contact struct { - Slack string - MailingList string `yaml:"mailing_list"` - GithubTeams []GithubTeams `yaml:"teams"` + Slack string + MailingList string `yaml:"mailing_list"` + PrivateMailingList string `yaml:"private_mailing_list"` + GithubTeams []GithubTeams `yaml:"teams"` } // GithubTeams represents a specific Github Team. @@ -125,6 +126,7 @@ type Context struct { Sigs []Group WorkingGroups []Group UserGroups []Group + Committees []Group } func pathExists(path string) bool { @@ -310,6 +312,10 @@ func main() { return strings.ToLower(ctx.UserGroups[i].Name) <= strings.ToLower(ctx.UserGroups[j].Name) }) + sort.Slice(ctx.Committees, func(i, j int) bool { + return strings.ToLower(ctx.Committees[i].Name) <= strings.ToLower(ctx.Committees[j].Name) + }) + err = createGroupReadme(ctx.Sigs, "sig") if err != nil { log.Fatal(err) @@ -325,6 +331,11 @@ func main() { log.Fatal(err) } + err = createGroupReadme(ctx.Committees, "committee") + if err != nil { + log.Fatal(err) + } + fmt.Println("Generating sig-list.md") outputPath := filepath.Join(baseGeneratorDir, sigListOutput) err = writeTemplate(filepath.Join(baseGeneratorDir, templateDir, listTemplate), outputPath, "markdown", ctx) diff --git a/generator/committee_readme.tmpl b/generator/committee_readme.tmpl new file mode 100644 index 000000000..c0337b472 --- /dev/null +++ b/generator/committee_readme.tmpl @@ -0,0 +1,57 @@ +{{- template "header" }} +# {{.Name}} Committee + +{{ .MissionStatement }} +{{- if .CharterLink }} +The [charter]({{.CharterLink}}) defines the scope and governance of the {{.Name}} Committee. +{{- end }} +{{- if .Meetings }} + +## Meetings +{{- range .Meetings }} +* {{.Description}}: [{{.Day}}s at {{.Time}} {{.TZ}}]({{.URL}}) ({{.Frequency}}). [Convert to your timezone](http://www.thetimezoneconverter.com/?t={{.Time}}&tz={{.TZ | tzUrlEncode}}). +{{- if .ArchiveURL }} + * [Meeting notes and Agenda]({{.ArchiveURL}}). +{{- end }} +{{- if .RecordingsURL }} + * [Meeting recordings]({{.RecordingsURL}}). +{{- end }} +{{- end }} + +{{- end }} +{{- if .Leadership }} +{{- if .Leadership.Chairs }} + +## Members +{{ range .Leadership.Chairs }} +* {{.Name}} (**[@{{.GitHub}}](https://github.com/{{.GitHub}})**){{if .Company}}, {{.Company}}{{end}} +{{- end }} +{{- end }} +{{- end }} + +## Contact + +{{- if .Contact.Slack }} +* [Slack](https://kubernetes.slack.com/messages/{{.Contact.Slack}}) +{{- end }} +{{- if .Contact.MailingList }} +* [Mailing list]({{.Contact.MailingList}}) +{{- end }} +{{- if .Contact.PrivateMailingList }} +* Private Mailing List: {{.Contact.PrivateMailingList}} +{{- end }} +{{- if .Label }} +* [Open Community Issues/PRs](https://github.com/kubernetes/community/labels/ug%2F{{.Label}}) +{{- end }} +{{ if .Contact.GithubTeams }} +## GitHub Teams + +The below teams can be mentioned on issues and PRs in order to get attention from the right people. +Note that the links to display team membership will only work if you are a member of the org. + +| Team Name | Details | Description | +| --------- |:-------:| ----------- | +{{- range .Contact.GithubTeams }} +| @kubernetes/{{.Name}} | [link](https://github.com/orgs/kubernetes/teams/{{.Name}}) | {{.Description}} | +{{- end }} +{{ end }} diff --git a/generator/list.tmpl b/generator/list.tmpl index 1299ee66a..d8970ceae 100644 --- a/generator/list.tmpl +++ b/generator/list.tmpl @@ -44,3 +44,10 @@ When the need arises, a [new SIG can be created](sig-wg-lifecycle.md) |[{{.Name}}]({{.Dir}}/README.md)|{{range .Leadership.Chairs}}* [{{.Name}}](https://github.com/{{.GitHub}}){{if .Company}}, {{.Company}}{{end}}
{{end}}|* [Slack](https://kubernetes.slack.com/messages/{{.Contact.Slack}})
* [Mailing List]({{.Contact.MailingList}})|{{range .Meetings}}* {{.Description}}: [{{.Day}}s at {{.Time}} {{.TZ}} ({{.Frequency}})]({{.URL}})
{{end}} {{- end }} {{ end }} +### Master Committee List + +| Name | Label | Members | Contact | +|------|--------|---------|---------| +{{- range .Committees}} +|[{{.Name}}]({{.Dir}}/README.md)|{{.Label}}|{{range .Leadership.Chairs}}* [{{.Name}}](https://github.com/{{.GitHub}}){{if .Company}}, {{.Company}}{{end}}
{{end}}|{{ if .Contact.Slack }}* [Slack](https://kubernetes.slack.com/messages/{{.Contact.Slack}})
{{ end }}{{ if .Contact.MailingList }}* [Mailing List]({{.Contact.MailingList}})
{{ end }}{{ if .Contact.PrivateMailingList }}* [Private Mailing List]({{.Contact.PrivateMailingList}}){{ end }} +{{- end }} diff --git a/hack/verify-generated-docs.sh b/hack/verify-generated-docs.sh index fab0cae72..73302358f 100755 --- a/hack/verify-generated-docs.sh +++ b/hack/verify-generated-docs.sh @@ -37,7 +37,7 @@ make 1>/dev/null mismatches=0 break=$(printf "=%.0s" $(seq 1 68)) -for file in $(ls ${CRT_DIR}/sig-*/README.md ${CRT_DIR}/wg-*/README.md ${CRT_DIR}/ug-*/README.md ${CRT_DIR}/sig-list.md ${CRT_DIR}/OWNERS_ALIASES); do +for file in $(ls ${CRT_DIR}/sig-*/README.md ${CRT_DIR}/wg-*/README.md ${CRT_DIR}/ug-*/README.md ${CRT_DIR}/committee-*/README.md ${CRT_DIR}/sig-list.md ${CRT_DIR}/OWNERS_ALIASES); do real=${file#$CRT_DIR/} if ! diff -q ${file} ${WORKING_DIR}/${real} &>/dev/null; then echo "${file} does not match ${WORKING_DIR}/${real}";