From f8404f32abd4ba16c778fc76c4162dc42a1d6bd3 Mon Sep 17 00:00:00 2001 From: Lars Kellogg-Stedman Date: Thu, 27 May 2021 18:03:46 -0400 Subject: [PATCH] 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 | 25 ++++++++ .github/workflows/precommit.yml | 22 +++++++ .gitignore | 1 + .pre-commit-config.yaml | 20 +++++++ .yamllint.yaml | 5 ++ Makefile | 25 ++++++++ README.md | 96 ++++++++++++++++++++++++++++++ config/repositories.txt | 1 + labels/flag.yml | 34 +++++++++++ labels/priority.yml | 16 +++++ labels/status.yml | 25 ++++++++ labels/topic.yml | 29 +++++++++ labels/type.yml | 26 ++++++++ proposed/effort.yml | 17 ++++++ proposed/size.yml | 17 ++++++ scripts/apply-labels.sh | 3 + scripts/build-readme.sh | 12 ++++ scripts/extract-docs.sh | 19 ++++++ scripts/extract-labels.sh | 3 + templates/README.md.in | 44 ++++++++++++++ 20 files changed, 440 insertions(+) create mode 100644 .github/workflows/apply-labels.yml create mode 100644 .github/workflows/precommit.yml create mode 100644 .gitignore create mode 100644 .pre-commit-config.yaml create mode 100644 .yamllint.yaml create mode 100644 Makefile create mode 100644 README.md create mode 100644 config/repositories.txt create mode 100644 labels/flag.yml create mode 100644 labels/priority.yml create mode 100644 labels/status.yml create mode 100644 labels/topic.yml create mode 100644 labels/type.yml create mode 100644 proposed/effort.yml create mode 100644 proposed/size.yml create mode 100644 scripts/apply-labels.sh create mode 100755 scripts/build-readme.sh create mode 100755 scripts/extract-docs.sh create mode 100755 scripts/extract-labels.sh create mode 100644 templates/README.md.in diff --git a/.github/workflows/apply-labels.yml b/.github/workflows/apply-labels.yml new file mode 100644 index 0000000..7bfb53a --- /dev/null +++ b/.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 diff --git a/.github/workflows/precommit.yml b/.github/workflows/precommit.yml new file mode 100644 index 0000000..525dbc2 --- /dev/null +++ b/.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/action@v2.0.3 + - 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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dcfc3ff --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +taxonomy.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..9747ebd --- /dev/null +++ b/.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] diff --git a/.yamllint.yaml b/.yamllint.yaml new file mode 100644 index 0000000..3dca7ad --- /dev/null +++ b/.yamllint.yaml @@ -0,0 +1,5 @@ +extends: default +rules: + document-start: false + truthy: + check-keys: false diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..9847da2 --- /dev/null +++ b/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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..09dbd41 --- /dev/null +++ b/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/ diff --git a/config/repositories.txt b/config/repositories.txt new file mode 100644 index 0000000..fd3e461 --- /dev/null +++ b/config/repositories.txt @@ -0,0 +1 @@ +CCI-MOC/issue-sandbox diff --git a/labels/flag.yml b/labels/flag.yml new file mode 100644 index 0000000..09143e9 --- /dev/null +++ b/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" diff --git a/labels/priority.yml b/labels/priority.yml new file mode 100644 index 0000000..33020f9 --- /dev/null +++ b/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" diff --git a/labels/status.yml b/labels/status.yml new file mode 100644 index 0000000..7390053 --- /dev/null +++ b/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" diff --git a/labels/topic.yml b/labels/topic.yml new file mode 100644 index 0000000..e7e5852 --- /dev/null +++ b/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" diff --git a/labels/type.yml b/labels/type.yml new file mode 100644 index 0000000..6625cd1 --- /dev/null +++ b/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" diff --git a/proposed/effort.yml b/proposed/effort.yml new file mode 100644 index 0000000..3f71df4 --- /dev/null +++ b/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. diff --git a/proposed/size.yml b/proposed/size.yml new file mode 100644 index 0000000..6b56370 --- /dev/null +++ b/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" diff --git a/scripts/apply-labels.sh b/scripts/apply-labels.sh new file mode 100644 index 0000000..2ee488f --- /dev/null +++ b/scripts/apply-labels.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +xargs -iREPO github-label-sync -l labels.json REPO < config/repositories.txt diff --git a/scripts/build-readme.sh b/scripts/build-readme.sh new file mode 100755 index 0000000..a12a2fc --- /dev/null +++ b/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 diff --git a/scripts/extract-docs.sh b/scripts/extract-docs.sh new file mode 100755 index 0000000..18ae547 --- /dev/null +++ b/scripts/extract-docs.sh @@ -0,0 +1,19 @@ +#!/bin/sh + +WANT_MULTIVALUE=null + +while getopts m ch; do + case $ch in + (m) WANT_MULTIVALUE=true + ;; + esac +done +shift $(( OPTIND - 1 )) + +yq -s -r --argjson WANT_MULTIVALUE $WANT_MULTIVALUE ' +.[]|select(.multivalue == $WANT_MULTIVALUE)|( +"#### \(.name)\n\n\(.description)\n", +(.labels[]|"- `\(.name)`: \(.description)"), +"\n" +) +' "$@" | sed 's/: null//' diff --git a/scripts/extract-labels.sh b/scripts/extract-labels.sh new file mode 100755 index 0000000..1e637a7 --- /dev/null +++ b/scripts/extract-labels.sh @@ -0,0 +1,3 @@ +#!/bin/sh + +yq -s '[.[]|.labels]|flatten' "$@" diff --git a/templates/README.md.in b/templates/README.md.in new file mode 100644 index 0000000..09c8e83 --- /dev/null +++ b/templates/README.md.in @@ -0,0 +1,44 @@ +# 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. + +@SINGLE_VALUE_AXES@ + +### Multi value axes + +Issues and PRs may have multiple labels from each of the following +axes. + +@MULTI_VALUE_AXES@ + +## 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/