cmd: add github labels tooling

Add new tooling to handle GitHub labels. This includes:

- A YAML template file (the master "labels database")

  This contains the master set of labels to be used for all Kata
  repositories. All labels have descriptions and a category.

- A script to generate the combined set of labels

  This merges the master set of labels with an optional
  repository-specific set of labels to produce a combined set of labels
  for a particular repository.

- A golang tool to check and summarise the labels database

  This can also be used to sort the labels database.

Fixes #1463.

Signed-off-by: James O. D. Hunt <[email protected]>

Author: James O. D. Hunt

.travis.yml

@@ -28,7 +28,8 @@ env:
 before_install:
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get update -qq              ; fi
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y -qq automake ; fi
-  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then travis_retry brew install bash; fi
+  - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then pip install --user yamllint          ; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then travis_retry brew install bash yamllint; fi
 
 script:
   - bash .ci/static-checks.sh github.com/kata-containers/tests

Makefile

@@ -30,11 +30,14 @@ ifneq ($(wildcard $(ARCH_FILE)),)
 include $(ARCH_FILE)
 endif
 
-default: checkcommits
+default: checkcommits github-labels
 
 checkcommits:
 	make -C cmd/checkcommits
 
+github-labels:
+	make -C cmd/github-labels
+
 ginkgo:
 	ln -sf . vendor/src
 	GOPATH=$(PWD)/vendor go build ./vendor/github.com/onsi/ginkgo/ginkgo

cmd/github-labels/Makefile

@@ -0,0 +1,32 @@
+#
+# Copyright (c) 2017-2019 Intel Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+TARGET = kata-github-labels
+SOURCES = $(shell find . -type f 2>&1 | grep -E '.*\.go$$')
+
+VERSION := ${shell cat ./VERSION}
+COMMIT_NO := $(shell git rev-parse HEAD 2> /dev/null || true)
+COMMIT := $(if $(shell git status --porcelain --untracked-files=no),"${COMMIT_NO}-dirty","${COMMIT_NO}")
+
+BINDIR := $(GOPATH)/bin
+DESTTARGET := $(abspath $(BINDIR)/$(TARGET))
+
+default: install
+
+check: $(SOURCES)
+	go test -v ./...
+
+$(TARGET): $(SOURCES)
+	go build -o "$(TARGET)" -ldflags "-X main.name=${TARGET} -X main.commit=${COMMIT} -X main.version=${VERSION}" .
+
+install: $(TARGET)
+	install -d $(shell dirname $(DESTTARGET))
+	install $(TARGET) $(DESTTARGET)
+
+clean:
+	rm -f $(TARGET)
+
+.PHONY: install clean

cmd/github-labels/README.md

@@ -0,0 +1,75 @@
+* [Overview](#overview)
+* [Generating the combined labels database](#generating-the-combined-labels-database)
+* [Checking and summarising the labels database](#checking-and-summarising-the-labels-database)
+    * [Show labels](#show-labels)
+    * [Show categories](#show-categories)
+    * [Check only](#check-only)
+    * [Full details](#full-details)
+
+# Overview
+
+The Kata Project uses a number of GitHub repositories. To allow issues and PRs
+to be handled consistently between repositories a standard set of issue labels
+are used. These labels are stored in YAML format in the master [labels
+database template](labels.yaml.in). This file is human-readable and
+machine-readable and self-describing (take a look at the file for the
+introductory description).
+
+Additionally, each repository can contain a set of additional
+(repository-specific) labels which are stored in a top-level YAML template
+file called `labels.yaml.in`.
+
+Expanding the templates and merging the two databases describes the full set
+of labels a repository uses.
+
+# Generating the combined labels database
+
+The combined labels database is generated by running the
+`github_labels.sh` script with the `generate` parameter, also passing the
+repository to generate the combined labels database for and the name of a file
+to write the combined database to:
+
+```sh
+$ ./github-labels.sh generate github.com/kata-containers/runtime /tmp/combined.yaml
+```
+
+The script validates the combined labels database by performing a number of
+checks including running the `kata-github-labels` tool (described in the
+[Checking and summarising the labels database](#checking-and-summarising-the-labels-database) section)
+in checking mode.
+
+# Checking and summarising the labels database
+
+The [`kata-github-labels`](github-labels.go) tool is used to check and
+summarise the labels database for each repository.
+
+## Show labels
+
+To display a summary of the labels:
+
+```sh
+$ kata-github-labels show labels labels.yaml
+```
+
+## Show categories
+
+To show all information about categories:
+
+```sh
+$ kata-github-labels show categories --with-labels labels.yaml
+```
+## Check only
+
+To only perform checks on specified labels database:
+
+```sh
+$ kata-github-labels check labels.yaml
+```
+
+## Full details
+
+To list all available options:
+
+```sh
+$ kata-github-labels -h
+```

cmd/github-labels/VERSION

@@ -0,0 +1 @@
+0.0.1

cmd/github-labels/check.go

@@ -0,0 +1,216 @@
+// Copyright (c) 2019 Intel Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"unicode"
+)
+
+func containsWhitespace(s string) bool {
+	for _, ch := range s {
+		if unicode.IsSpace(ch) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func isLower(s string) bool {
+	for _, ch := range s {
+		if !unicode.IsLetter(ch) {
+			continue
+		}
+
+		if !unicode.IsLower(ch) {
+			return false
+		}
+	}
+
+	return true
+}
+
+func checkCategory(c Category) error {
+	if c.Name == "" {
+		return fmt.Errorf("category name cannot be blank: %+v", c)
+	}
+
+	if containsWhitespace(c.Name) {
+		return fmt.Errorf("category name cannot contain whitespace: %+v", c)
+	}
+
+	if !isLower(c.Name) {
+		return fmt.Errorf("category name must be all lower case: %+v", c)
+	}
+
+	if c.Description == "" {
+		return fmt.Errorf("category description cannot be blank: %+v", c)
+	}
+
+	first := c.Description[0]
+
+	if !unicode.IsUpper(rune(first)) {
+		return fmt.Errorf("category description needs initial capital letter: %+v", c)
+	}
+
+	if !strings.HasSuffix(c.Description, ".") {
+		return fmt.Errorf("category description needs trailing period: %+v", c)
+	}
+
+	return nil
+}
+
+func checkLabel(l Label) error {
+	if l.Name == "" {
+		return fmt.Errorf("label name cannot be blank: %+v", l)
+	}
+
+	if !isLower(l.Name) {
+		return fmt.Errorf("label name must be all lower case: %+v", l)
+	}
+
+	if containsWhitespace(l.Name) {
+		return fmt.Errorf("label name cannot contain whitespace: %+v", l)
+	}
+
+	if l.Description == "" {
+		return fmt.Errorf("label description cannot be blank: %+v", l)
+	}
+
+	first := l.Description[0]
+
+	if !unicode.IsUpper(rune(first)) {
+		return fmt.Errorf("label description needs initial capital letter: %+v", l)
+	}
+
+	if l.CategoryName == "" {
+		return fmt.Errorf("label category name cannot be blank: %+v", l)
+	}
+
+	if l.Colour == "" {
+		return fmt.Errorf("label colour cannot be blank: %+v", l)
+	}
+
+	return nil
+}
+
+func checkLabelsAndCategories(lf *LabelsFile) error {
+	catCount := 0
+
+	var catNameMap map[string]int
+	var catDescMap map[string]int
+
+	var labelNameMap map[string]int
+	var labelDescMap map[string]int
+
+	catNameMap = make(map[string]int)
+	catDescMap = make(map[string]int)
+	labelNameMap = make(map[string]int)
+	labelDescMap = make(map[string]int)
+
+	for _, c := range lf.Categories {
+		if err := checkCategory(c); err != nil {
+			return err
+		}
+
+		catCount++
+
+		if _, ok := catNameMap[c.Name]; ok {
+			return fmt.Errorf("duplicate category name: %+v", c)
+		}
+
+		catNameMap[c.Name] = 0
+
+		if _, ok := catDescMap[c.Description]; ok {
+			return fmt.Errorf("duplicate category description: %+v", c)
+		}
+
+		catDescMap[c.Description] = 0
+	}
+
+	if catCount == 0 {
+		return errors.New("no categories found")
+	}
+
+	labelCount := 0
+
+	for _, l := range lf.Labels {
+		if err := checkLabel(l); err != nil {
+			return err
+		}
+
+		if _, ok := labelNameMap[l.Name]; ok {
+			return fmt.Errorf("duplicate label name: %+v", l)
+		}
+
+		labelNameMap[l.Name] = 0
+
+		if _, ok := labelDescMap[l.Description]; ok {
+			return fmt.Errorf("duplicate label description: %+v", l)
+		}
+
+		labelDescMap[l.Description] = 0
+
+		labelCount++
+
+		catName := l.CategoryName
+
+		var value int
+		var ok bool
+		if value, ok = catNameMap[catName]; !ok {
+			return fmt.Errorf("invalid category %v found for label %+v", catName, l)
+		}
+
+		// update
+		value++
+		catNameMap[catName] = value
+	}
+
+	if labelCount == 0 {
+		return errors.New("no labels found")
+	}
+
+	if debug {
+		fmt.Printf("DEBUG: category count: %v\n", catCount)
+		fmt.Printf("DEBUG: label count: %v\n", labelCount)
+	}
+
+	for name, count := range catNameMap {
+		if count == 0 {
+			return fmt.Errorf("category %v not used", name)
+		}
+
+		if debug {
+			fmt.Printf("DEBUG: category %v: label count: %d\n",
+				name, count)
+		}
+	}
+
+	return nil
+}
+
+func check(lf *LabelsFile) error {
+	if lf.Description == "" {
+		return errors.New("description cannot be blank")
+	}
+
+	if lf.Repo == "" {
+		return errors.New("repo cannot be blank")
+	}
+
+	if len(lf.Categories) == 0 {
+		return errors.New("no categories")
+	}
+
+	if len(lf.Labels) == 0 {
+		return errors.New("no labels")
+	}
+
+	return checkLabelsAndCategories(lf)
+}