MOC project planning label taxonomy

This repository contains the standard label taxonomy for MOC
repositories as well as tooling to apply the taxonomy to selected
repositories.

Part of CCI-MOC/ops-issues#270

.github/workflows/apply-labels.yml

@@ -0,0 +1,25 @@
+name: apply-labels
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  apply-labels:
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/massopencloud/gh-tools:3bd6ef2
+    steps:
+      - name: Checkout out repository
+        uses: actions/checkout@v2
+
+      - name: Generate labels.json
+        run: |
+          make labels.json
+
+      - name: Apply labels
+        env:
+          GITHUB_ACCESS_TOKEN: ${{ secrets.GH_API_TOKEN }}
+        run: |
+          sh scripts/apply-labels.sh

.github/workflows/precommit.yml

@@ -0,0 +1,22 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: check out repository
+        uses: actions/checkout@v2
+      - name: set up python
+        uses: actions/setup-python@v2
+      - name: run pre-commit checks
+        uses: pre-commit/[email protected]
+      - name: check for out-of-date files
+        run: |
+          if ! make -q; then
+            echo "ERROR: files are out of date; please run make." >&2
+            exit 1
+          fi

.gitignore

@@ -0,0 +1 @@
+taxonomy.md

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+---
+repos:
+  - repo: git://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-symlinks
+      - id: detect-private-key
+
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.26.1
+    hooks:
+      - id: yamllint
+        files: \.(yaml|yml)$
+        types: [file, yaml]

.yamllint.yaml

@@ -0,0 +1,5 @@
+extends: default
+rules:
+  document-start: false
+  truthy:
+    check-keys: false

Makefile

@@ -0,0 +1,25 @@
+LABELS = $(wildcard labels/*.yml)
+GENERATED = \
+	    labels.json \
+	    README.md \
+	    single-value-axes.md \
+	    multi-value-axes.md
+
+all: README.md
+
+README.md: templates/README.md.in single-value-axes.md multi-value-axes.md
+	sh scripts/build-readme.sh $< > $@ || { rm -f $@; exit 1; }
+
+labels.json: scripts/extract-labels.sh $(LABELS)
+	sh scripts/extract-labels.sh $(LABELS) > $@ || { rm -f $@; exit 1; }
+
+single-value-axes.md: scripts/extract-docs.sh $(LABELS)
+	sh scripts/extract-docs.sh $(LABELS) > $@ || { rm -f $@; exit 1; }
+
+multi-value-axes.md: scripts/extract-docs.sh $(LABELS)
+	sh scripts/extract-docs.sh -m $(LABELS) > $@ || { rm -f $@; exit 1; }
+
+clean:
+	rm -f $(GENERATED)
+
+.INTERMEDIATE: multi-value-axes.md single-value-axes.md

README.md

@@ -0,0 +1,96 @@
+# A Taxonomy for Issue and PR Labels
+
+## Overview
+
+Labels are organized into a series of [axes](#axes) indicated by a
+prefix on the label. There are no "top-level" labels; every label
+belongs to an axis.
+
+For axes with an implied ordering (such as "priority"), colors are
+allocated to labels along a gradient. For axes like "type" in which
+labels represent distinct, unrelated values, colors can be chosen at
+will.
+
+## Axes
+
+> This documentation is generated automatically from the YAML
+> files in the [`labels/`](labels/) directory.
+
+### Single value axes
+
+Issues and PRs may have no more than one label from the following
+axes.
+
+#### Priority
+
+The `priority` axis describes the criticality of an issue.
+
+- `priority/critical`: This task is immediately necessary
+- `priority/high`: This task is needed as soon as possible
+- `priority/medium`: This task should be scheduled.
+- `priority/low`: The same as "no priority"
+
+
+#### Status
+
+The `status` axis describes the current condition of the issue or PR.
+
+- `status/invalid`: This doesn't seem right
+- `status/wontfix`: We will not work on this issue
+- `status/blocked`: This has a dependency
+- `status/accepted`: We have accepted item into a sprint
+
+
+#### Type
+
+The `type` axis describes in broad terms what sort of work is required by the issue or PR.
+
+- `type/bug`: Something isn't working
+- `type/enhancement`: This is a request for a new feature
+- `type/documentation`: This task is mostly about documentation
+- `type/research`: This task is primarily about information discovery
+- `type/discussion`: We need to talk about this
+
+
+
+### Multi value axes
+
+Issues and PRs may have multiple labels from each of the following
+axes.
+
+#### Flag
+
+The `flag` axis is used to bring attention to an issue or a pull request.
+
+- `flag/good first issue`: This is a good place to start
+- `flag/help wanted`: I need some help with this task
+- `flag/needs description`: This task needs a description
+- `flag/added post planning`: This item was added after sprint planning
+- `flag/question`: This item requires additional details
+- `flag/external`: This items is tracking an external issue.
+
+
+#### Topic
+
+The `topic` axis is for grouping tasks related to a certain subject. A task may have more than one `topic` label.
+
+- `topic/monitoring`: This task has to do with monitoring
+- `topic/devops`: This task furthers our devops related goals
+- `topic/policy`: This task is about how we do things.
+- `topic/mghpcc`: This task involves work at MGHPCC.
+- `topic/website`: This task involves the MOC website.
+
+
+
+## Resources
+
+Thoughtful posts on taxonomy, color, etc:
+
+- https://medium.com/@dave_lunny/sane-github-labels-c5d2e6004b63
+- https://seantrane.com/posts/logical-colorful-github-labels-18230/
+- https://robinpowered.com/blog/best-practice-system-for-organizing-and-tagging-github-issues
+
+Good for color gradients:
+
+- https://mdigi.tools/color-shades/
+- https://noeldelgado.github.io/shadowlord/

config/repositories.txt

@@ -0,0 +1 @@
+CCI-MOC/issue-sandbox

labels/flag.yml

@@ -0,0 +1,34 @@
+name: Flag
+multivalue: true
+description: >-
+  The `flag` axis is used to bring attention to an issue or a pull
+  request.
+labels:
+  - name: flag/good first issue
+    aliases:
+      - good first issue
+    description: This is a good place to start
+    color: "7057ff"
+  - name: flag/help wanted
+    aliases:
+      - help wanted
+    description: I need some help with this task
+    color: "008672"
+  - name: flag/needs description
+    aliases:
+      - needs_description
+    description: This task needs a description
+    color: "ededed"
+  - name: flag/added post planning
+    aliases:
+      - added_post_planning
+    description: This item was added after sprint planning
+    color: "ccff4c"
+  - name: flag/question
+    aliases:
+      - question
+    description: This item requires additional details
+    color: "d876e3"
+  - name: flag/external
+    description: This items is tracking an external issue.
+    color: "9a74d8"

labels/priority.yml

@@ -0,0 +1,16 @@
+name: Priority
+description: >-
+  The `priority` axis describes the criticality of an issue.
+labels:
+  - name: priority/critical
+    description: This task is immediately necessary
+    color: "fc1d47"
+  - name: priority/high
+    description: This task is needed as soon as possible
+    color: "fc4f70"
+  - name: priority/medium
+    description: This task should be scheduled.
+    color: "fd8199"
+  - name: priority/low
+    description: The same as "no priority"
+    color: "ffffff"

labels/status.yml

@@ -0,0 +1,25 @@
+name: Status
+description: >-
+  The `status` axis describes the current condition of the issue or
+  PR.
+labels:
+  - name: status/invalid
+    aliases:
+      - invalid
+    description: This doesn't seem right
+    color: "e4e669"
+  - name: status/wontfix
+    aliases:
+      - wontfix
+    description: We will not work on this issue
+    color: "ffffff"
+  - name: status/blocked
+    aliases:
+      - blocked
+    description: This has a dependency
+    color: "873719"
+  - name: status/accepted
+    aliases:
+      - accepted
+    description: We have accepted item into a sprint
+    color: "ededed"

labels/topic.yml

@@ -0,0 +1,29 @@
+name: Topic
+multivalue: true
+description: >-
+  The `topic` axis is for grouping tasks related to a certain subject.
+  A task may have more than one `topic` label.
+labels:
+  - name: topic/monitoring
+    aliases:
+      - monitoring
+    description: This task has to do with monitoring
+    color: "4eed68"
+  - name: topic/devops
+    aliases:
+      - gitopsify
+    description: This task furthers our devops related goals
+    color: "e99695"
+  - name: topic/policy
+    description: This task is about how we do things.
+    color: "66ccff"
+  - name: topic/mghpcc
+    aliases:
+      - mghpcc
+    description: This task involves work at MGHPCC.
+    color: "5319e7"
+  - name: topic/website
+    aliases:
+      - website
+    description: This task involves the MOC website.
+    color: "334A9E"

labels/type.yml

@@ -0,0 +1,26 @@
+name: Type
+description: >-
+  The `type` axis describes in broad terms what sort of work is
+  required by the issue or PR.
+labels:
+  - name: type/bug
+    aliases:
+      - bug
+    description: Something isn't working
+    color: "d73a4a"
+  - name: type/enhancement
+    aliases:
+      - enhancement
+    description: This is a request for a new feature
+    color: "a2eeef"
+  - name: type/documentation
+    description: This task is mostly about documentation
+    color: "0075ca"
+  - name: type/research
+    aliases:
+      - research
+    description: This task is primarily about information discovery
+    color: "e99695"
+  - name: type/discussion
+    description: We need to talk about this
+    color: "ff99ff"

proposed/effort.yml

@@ -0,0 +1,17 @@
+name: Effort
+description: >-
+  The `effort` axis describes how much work we believe will be required
+  to resolve the issue.
+labels:
+  - name: effort/hours
+    color: "ffe0b3"
+    description: This task should take at most a few hours to complete.
+  - name: effort/days
+    color: "ffcc80"
+    description: This task may take several days to complete.
+  - name: effort/weeks
+    color: "ffb84d"
+    description: This task may take several weeks to complete.
+  - name: effort/∞
+    color: "b36b00"
+    description: This task is too large to be actionable.

proposed/size.yml

@@ -0,0 +1,17 @@
+name: Size
+description: >-
+  The `size` axis describes how much work we believe will be required
+  to resolve the issue.
+labels:
+  - name: size/x-small
+    color: "ffe0b3"
+  - name: size/small
+    color: "ffcc80"
+  - name: size/medium
+    color: "ffb84d"
+  - name: size/large
+    color: "ffa31a"
+  - name: size/x-large
+    color: "e68a00"
+  - name: size/∞
+    color: "b36b00"

scripts/apply-labels.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+xargs -iREPO github-label-sync -l labels.json REPO < config/repositories.txt

scripts/build-readme.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+sed '
+/@SINGLE_VALUE_AXES@/ {
+	r single-value-axes.md
+	d
+}
+/@MULTI_VALUE_AXES@/ {
+	r multi-value-axes.md
+	d
+}
+' templates/README.md.in