Ruled Labels

简介

ruled-labels 与 glabel yaml 格式兼容，并允许指定关于标签的附加规则。这些规则在 yaml 文件中描述。

ruled-labels 可以处理

• 标签及其属性的列表

• 标签规则

• 测试用例的描述

入门指南

完成安装后，系统将出现一个名为 ruled-labels 的新命令

您至少需要一个 规则 文件。通常命名为 specs.yml，如果使用此名称，ruled-labels 将默认找到它。

有了您的 规则，您可以通过调用 ruled-labels 来检查一组标签。下面是这样的

ruled-labels check --labels A1,B1

或者，您也可以这样调用

ruled-labels check -l A1 -l B1

以下调用是无效的

• ruled-labels check--labelsA1, B1

• ruled-labels check--labelsA1 B1

查看使用说明以了解有关可用命令和选项的更多信息。

在大多数情况下，您不会手动调用检查命令，而是让 CI 处理。

首先，您可能需要获取 PR 的标签

API_BASE=https://api.github.com/repos
REPO=...
GITHUB_PR=1234
labels=$( curl -H "Authorization: token $GITHUB_TOKEN" -s "$API_BASE/$REPO/pulls/$GITHUB_PR" | jq '.labels | .[] | .name' | tr "\n" ",")

现在您可以删除前面的 ,，它没有用

labels_args=${labels: :-1}

在使用 labels_args 之前，您想确保您正在使用 IFS=","，这样您的 shell 就不会将包含空格的标签分成两个字符串，一个是有效的标签，另一个将失败。

最后运行检查

ruled-labels check --dev --labels $labels_args

如果您更喜欢使用 Docker 镜像，下面是这样的

docker run --rm -i -e labels_args -v $PWD/:$MOUNT $IMAGE check $MOUNT/$CHECK_SPECS --dev --labels $labels_args

安装

目前没有二进制包，因此您需要使用 cargo 在您的系统上构建和安装 ruled-labels。

cargo install --locked --git https://github.com/chevdor/ruled_labels

Docker

如果您不想安装 Rust 和 Cargo，并且已经安装了 Docker，您可能更喜欢运行 ruled-labels 的 Docker 版本。下一章将解释如何进行。

运行

Docker 命令可能相当长，因此您可能想设置一个别名

    alias ruled-labels='docker run --rm -it ruled-labels'

设置此别名后，您只需调用 ruled-labels 命令即可使用 ruled-labels。

    ruled-labels --version

如果您希望命令更简短，可以为 rl 而不是 ruled-labels 设置别名。

这超出了本文档的范围，但请注意，您不能直接调用 ruled-labels 检查并期望它在您的本地 specs.yaml 上工作。为了使其工作，您需要将您的 specs.yaml 挂载到容器中。这看起来像这样

    docker run --rm -it -v $PWD/specs.yaml:/usr/local/bin/specs.yaml <literal>ruled-labels</literal> list

构建

您可以从 chevdor/ruled-labels 拉取 docker 镜像或自行构建

    docker build -t ruled-labels .

特性

• 基于规则的引擎

• 规则以 yaml 定义

• lint：lint 命令可以帮助您验证 yaml 文件

• list：显示规则的摘要

• test：您可以定义一组测试场景，以检查您的规格以确定您没有遗漏任何内容

• check：CI 可以调用此命令来检查一组标签是否与您的规格和规则相符

用法

帮助

This utility allows checking labels based on rules

Usage: ruled-labels [OPTIONS] <COMMAND>

Commands:
  list   List all the rules
  lint   Lint the rules
  check  Check label set against the rules
  test   Run tests using rules and a test set
  help   Print this message or the help of the given subcommand(s)

Options:
      --no-color  Output without any coloring, this is useful for documentation and CI system where the color code pollute the output
  -d, --dev       The output is more developer oriented
  -h, --help      Print help information
  -V, --version   Print version information

lint

PASSED  The file specs.yaml looks OK

list

name: chevdor/glabel
desc: Import from chevdor/glabel
labels: 14
Rules:
 - Some topics (X labels) (some_topics)
 - Exactly one visibility label (b_rules)
 - Note Worthy need one Prio label (b_need_p)
 - Note Worthy implies no J label (b1_excludes_j)
 - Exclude all Ds (exclude_all_d)
 - Require all of J
 - Require 1 P and no X (single_p_no_x) DISABLED

test

Tests specs: tests.yaml
Specs file : specs.yaml

    ▶️ Running test  1: Pass
    PASSED  Pass

    ▶️ Running test  2: Fail - b_rules
You need to include one of the B* label(s)
    PASSED  Fail - b_rules

    ▶️ Running test  3: Fail - some_topics
You need to include some of the J2, X1, X2 label(s)
    PASSED  Fail - some_topics

    ▶️ Running test  4: Fail - b_need_p
Since you have one of the B* label(s), you need to include one of the P* label(s) and you need to exclude all of the P1 label(s)
    PASSED  Fail - b_need_p

    ▶️ Running test  5: Fail - b1_excludes_j
Since you have one of the B1 label(s), you need to exclude all of the J* label(s)
    PASSED  Fail - b1_excludes_j

    ▶️ Running test  6: Fail - b1_excludes_j 2
Since you have one of the B1 label(s), you need to exclude all of the J* label(s)
    PASSED  Fail - b1_excludes_j 2
PASSED  All expectations are OK

check

s = "B0"
s = "A1"
        FAILED  Some topics (X labels) | You need to include some of the X2, J2, X1 label(s)
        PASSED  Exactly one visibility label | You need to include one of the B* label(s)
        FAILED  Note Worthy need one Prio label | Since you have one of the B* label(s), you need to include one of the P* label(s) and you need to exclude all of the P1 label(s)
        SKIPPED Note Worthy implies no J label | Since you have one of the B1 label(s), you need to exclude all of the J* label(s)
        PASSED  Exclude all Ds | You need to exclude all of the D* label(s)
        FAILED  Require all of J | You need to include all of the J* label(s)
        SKIPPED Require 1 P and no X | You need to include one of the P* label(s) and you need to exclude all of the X1, X2 label(s)
FAILED  chevdor/glabel v0.1.0 for labels A1, B0

Vscode yaml

将配置添加到 yaml 插件（由 RedHat 提供）

"yaml.customTags": [
    "!none_of sequence",
    "!one_of sequence",
    "!some_of sequence",
    "!all_of sequence",
]

Yaml 规格说明

规则

---
# tag::header[]
name: chevdor/glabel
version: 0.1.0
description: Import from chevdor/glabel
# end::header[]

# tag::labels[]
labels:
  - name: A1-foo
    description: Foo
    color: d73a4a
  - name: A2-bar
    description: Bar
    color: d73a4a
# end::labels[]
  - name: X1-frontend
    description: Frontend
    color: d73a4a
  - name: X2-backend
    description: Frontend
    color: d73a4a
  - name: X3-documentation
    description: Improvements or additions to documentation
    color: 0075ca
  - name: P1-low_prio
    description: Low prio
    color: ffffff
  - name: P2-low_prio
    description: Low prio
    color: ffffff
  - name: P3-low_prio
    description: Low prio
    color: ffffff
  - name: B0-silent
    description: silent
    color: ffffff
  - name: B1-note_worthy
    description: note worthy
    color: ffffff
  - name: B2-important
    description: important
    color: ffffff
  - name: J1-junk1
    description: junk1
    color: ffffff
  - name: J2-junk2
    description: junk2
    color: ffffff
  - name: D1-disable1
    description: diable1
    color: ffffff

# tag::rules[]
rules:
  - name: Some topics (X labels)
    id: some_topics
    spec:
      require: !some_of
        - X1
        - X2
        - J2
# end::rules[]

  - name: Exactly one visibility label
    id: b_rules
    tags: [ CI ]
    priority: 1000
    description: |
      This rule ensures we have a single visibility label.
      It is important to void conflicts such as having a PR
      labels as both important and unsubstantial.
    spec:
      require: !one_of
        - B*
      exclude: ~


  - name: Note Worthy need one Prio label
    id: b_need_p
    tags: [v2, CI]
    priority: 100
    spec:
      # when we have one of the B labels
      when: !one_of
        - B*
      # we need exactly one of the P labels
      require: !one_of
        - P*
      # but we don't want the P1 labels
      exclude: !all_of
        - P1

  - name: Note Worthy implies no J label
    id: b1_excludes_j
    spec:
      when: !one_of
        - B1
      exclude: !all_of
        - J*

  - name: Exclude all Ds
    id: exclude_all_d
    disabled: false   # default
    priority: 100     # default
    spec:
      exclude: !all_of
        - D*

  - name: Require all of J
    ide: require_all_j
    spec:
      require: !all_of
        - J*

  - name: Require 1 P and no X
    id: single_p_no_x
    disabled: true
    spec:
      require: !one_of
        - P*
      exclude: !all_of ["X1", "X2"]

test

name: Name of the test
spec_file: specs.yaml

specs:
  - name: Pass
    only: true
    labels:
      - B0-silent
      - X1-bar
      - X2-bar
      - X3-foobar
      - J1
      - J2
      - P2
    expected: true

  - name: Fail - b_rules
    filter:
      id: [ b_rules ]
    labels:
      - B1-note_worthy
      - B0-silent
    expected: false

  - name: Fail - some_topics
    filter:
      id: [ some_topics ]
    skip: true
    labels:
      - B0-silent
    expected: false

  - name: Fail - b_need_p
    filter:
      id: [ b_need_p ]
    labels:
      - B1
    expected: false

  - name: Fail - b1_excludes_j
    filter:
      id: [ b1_excludes_j ]
    labels:
      - B1
      - J1
      - J2
    expected: false

  - name: Fail - b1_excludes_j 2
    filter:
      id: [ b1_excludes_j ]
    labels:
      - B1
      - J1
    expected: false

术语表

为了理解术语以及 LabelMatch、LabelMatchSet、Labels、LabelId 等，请参阅 Rust 文档。您可以使用以下方法生成和打开它：

cargo doc --no-deps --open

许可证

Copyright 2021-2022 - Wilfried Kopp aka. Chevdor <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.