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

@@ -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-<sig-name>/README.md
 wg-<working-group-name>/README.md
 ug-<user-group-name>/README.md
+committee-<committee-name>/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
 <!-- END CUSTOM CONTENT -->
 ```
+
+### 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
+```

generator/aliases.tmpl

@@ -20,3 +20,9 @@ aliases:
     - {{.GitHub}}
     {{- end}}
   {{- end}}
+  {{- range .Committees}}
+  {{.Dir}}:
+    {{- range .Leadership.Chairs}}
+    - {{.GitHub}}
+    {{- end}}
+  {{- end}}

generator/app.go

@@ -73,9 +73,10 @@ type Meeting struct {
 
 // Contact represents the various contact points for a group.
 type Contact struct {
-	Slack       string
+	Slack              string
-	MailingList string        `yaml:"mailing_list"`
+	MailingList        string        `yaml:"mailing_list"`
-	GithubTeams []GithubTeams `yaml:"teams"`
+	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)

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 }}

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}}<br>{{end}}|* [Slack](https://kubernetes.slack.com/messages/{{.Contact.Slack}})<br>* [Mailing List]({{.Contact.MailingList}})|{{range .Meetings}}* {{.Description}}: [{{.Day}}s at {{.Time}} {{.TZ}} ({{.Frequency}})]({{.URL}})<br>{{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}}<br>{{end}}|{{ if .Contact.Slack }}* [Slack](https://kubernetes.slack.com/messages/{{.Contact.Slack}})<br>{{ end }}{{ if .Contact.MailingList }}* [Mailing List]({{.Contact.MailingList}})<br>{{ end }}{{ if .Contact.PrivateMailingList }}* [Private Mailing List]({{.Contact.PrivateMailingList}}){{ end }}
+{{- end }}

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}";