diff --git a/source/00_supperthomas/13_action/images/image-20240827194954077.png b/source/00_supperthomas/13_action/images/image-20240827194954077.png new file mode 100644 index 0000000..bc0e637 Binary files /dev/null and b/source/00_supperthomas/13_action/images/image-20240827194954077.png differ diff --git a/source/00_supperthomas/13_action/images/image-20240827195038063.png b/source/00_supperthomas/13_action/images/image-20240827195038063.png new file mode 100644 index 0000000..7f33671 Binary files /dev/null and b/source/00_supperthomas/13_action/images/image-20240827195038063.png differ diff --git a/source/00_supperthomas/13_action/labeler.md b/source/00_supperthomas/13_action/labeler.md new file mode 100644 index 0000000..593bff2 --- /dev/null +++ b/source/00_supperthomas/13_action/labeler.md @@ -0,0 +1,200 @@ +# RT-Thread PR:开启自动化标签新时代 + +## 引言 + +在现代软件开发中,效率与自动化是两大关键要素。尤其是在多人协作的开源项目中,保持一致的代码审查流程和项目管理对于项目的顺利进行至关重要。而GitHub Actions作为GitHub提供的一项持续集成与持续交付(CI/CD)服务,已经成为项目自动化不可或缺的工具之一。 + +在我的工作过程中,我意识到标签(labels)在项目管理中的重要性,尤其是在PR(Pull Request)和Issue的处理上。通过标签,项目维护者能够更快地识别问题的类型,合理分配优先级,从而提高项目的整体效率。然而,手动添加标签对于大型项目来说可能是个繁琐且容易出错的过程。这正是GitHub Actions中labeler自动标签功能大放异彩的地方。 + +在这篇文档中,我将详细介绍如何利用GitHub Actions的labeler自动标签功能,通过配置简单的规则,让GitHub自动为你的PR打上合适的标签。我还会结合我在RT-Thread项目中的实际应用,展示这一功能如何帮助提升项目管理效率。 + +## 问题描述 + +在没有自动标签功能之前,PR和Issue的管理通常是手动完成的。随着项目规模的扩大,手动管理标签会变得越来越繁琐且容易出错。手动标签管理存在以下几个不便之处: + +**1. 时间消耗巨大** + +**2. 标签一致性难以保持** + +**3. 难以及时响应** + +**4. 增加项目维护者的负担** + +**5. 难以筛选和优先处理** + +**6. 协作难度加大** + +可以看出,手动标签管理存在诸多不便,影响了项目的效率和协作。尤其是在团队规模较大、PR和Issue数量较多的项目中,手动标签不仅增加了工作量,还容易导致标签不一致、处理延迟等问题。 + +## 功能概述 + +**什么是labeler自动标签功能?** + +Labeler是GitHub Actions中的一个功能,旨在根据文件路径、文件名模式、甚至代码内容等规则,自动为PR和Issue添加标签。自动标签功能不仅可以帮助开发者快速识别PR的性质,还能为项目维护者节省时间,提升工作效率。 + +参考仓库链接 https://github.com/actions/labeler + +**如何通过GitHub Actions实现自动标签?** + +### 第一步 添加工作流 + +在`.github/workflows/auto_labeler.yml`目录下面的workflow下面添加触发的action,内容如下: + +```yml +name: "Pull Request Labeler" +on: +- pull_request_target + +jobs: + labeler: + permissions: + contents: read + pull-requests: write + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v5 + with: + configuration-path: '.github/labeler.yml' +``` + +这里的`pull_request_target`和`pull_request` 的区别是`pull_request_target` 更安全,`pull_request`需要TOKEN来授权。 + +labeler有以下参数可以设置。可以参考上面`labeler`中的`with`来设置, 常用的就是labeler.yml中的规则文件,放在`.github` 默认是放在这里的。 + +| 姓名 | 描述 | 默认 | +| -------------------- | ------------------------------------------------------------ | --------------------- | +| `repo-token` | 用于授权标签更改的令牌。通常是 GITHUB_TOKEN 密钥 | `github.token` | +| `configuration-path` | 标签配置文件的路径。如果该文件在运行器上指定的路径下不存在,则操作将通过 Github API 从源存储库读取。 | `.github/labeler.yml` | +| `sync-labels` | 当匹配的文件被撤销或不再被 PR 更改时是否删除标签 | `false` | +| `dot` | 是否自动包含以点开头的路径(例如`.github`) | `true` | +| `pr-number` | 要更新的拉取请求的数量,而不是从工作流上下文中检测 | 不适用 | + +### 第二步 设置规则 + +GitHub Actions通过YAML文件进行配置,labeler功能的实现也依赖于此。你可以在项目的`.github`文件夹下创建一个`labeler.yml`文件,在其中定义不同的标签规则。当有人提交PR时,GitHub Actions会自动运行这些规则,并根据匹配结果为其打上相应的标签。 + +内容参考如下,这里就根据PR的不同文件进行设置`label` + +```yml +BSP: +- changed-files: + - any-glob-to-any-file: bsp/** + +'BSP: STM32': +- changed-files: + - any-glob-to-any-file: bsp/stm32/** + +testcase: +- changed-files: + - any-glob-to-any-file: examples/** + +tools: +- changed-files: + - any-glob-to-any-file: tools/** + +Kernel: +- changed-files: + - any-glob-to-any-file: src/** + +action: +- changed-files: + - any-glob-to-any-file: .github/** + - any-glob-to-any-file: tools/ci/** + +Doc: +- changed-files: + - any-glob-to-any-file: documentation/** +``` + +这些label可以是新建的也可以是原有的 + +之前原有的见链接: https://github.com/RT-Thread/rt-thread/issues/labels + +这里简单介绍以下参数含义: + +```yml +# any-glob-to-any-file 任何glob +root: +- changed-files: + - any-glob-to-any-file: '*' + +# 一个*代表根目录下的文件不包含文件夹中的内容, **代表要包含下面的子文件夹以及根文件夹的内容 +AnyChange: +- changed-files: + - any-glob-to-any-file: '**' + +#添加Documentation 到所有的docs/下面的所有文件夹及文件 +Documentation: +- changed-files: + - any-glob-to-any-file: docs/** + +# 添加Documentation 到所有的docs/下面的文件, 不包含文件夹 +Documentation: +- changed-files: + - any-glob-to-any-file: docs/* + +# 包含docs/*或者guides/文件夹下面的文件 +Documentation: +- changed-files: + - any-glob-to-any-file: + - docs/* + - guides/* + +## 另一种方式等同上面 +Documentation: +- changed-files: + - any-glob-to-any-file: ['docs/*', 'guides/*'] + +# 仓库中的所有以md结尾的文件 +Documentation: +- changed-files: + - any-glob-to-any-file: '**/*.md' + + +# src下面的所有文件夹内的文件, 除了docs下面的目录下的内容 +source: +- all: + - changed-files: + - any-glob-to-any-file: 'src/**/*' + - all-globs-to-all-files: '!src/docs/*' + +# 任何PR到feature分支上的PR +feature: + - head-branch: ['^feature', 'feature'] + +# main分支上release的PR +release: + - base-branch: 'main' +``` + +## 实际应用与优势 + +**提高代码审查效率** + +自动标签功能可以帮助项目维护者在大量PR中快速找到他们关心的内容。通过自动为PR打上标签,团队成员可以更轻松地分配任务、安排优先级。这特别适用于大型项目,避免了手动标记的繁琐。 + +**使项目管理更为自动化** + +通过GitHub Actions自动标签功能,项目管理可以更加自动化和一致。无论是处理PR还是代码审查流程,自动标签功能都能确保每个步骤都按照预期执行,减少人为错误。 + +**适用的典型项目场景分析** + +在一些开源项目中,参与者众多且背景各异。自动标签功能可以帮助项目维护者快速识别不同领域的贡献。例如,文档修改、功能新增、Bug修复等都可以通过标签区分开来,方便不同领域的维护者参与审查。 + +## 在RT-Thread项目中的应用 + +祥见PR + +https://github.com/RT-Thread/rt-thread/pull/9347 + +![image-20240827194954077](images/image-20240827194954077.png) + +如果你PR的时候发现有下面的github-actions,代表功能生效了。 + +![image-20240827195038063](images/image-20240827195038063.png) + + + +--- + +希望这部分内容能帮助你更好地了解GitHub Actions labeler的功能。如果你有其他想补充的内容或者需要更多细节,随时告诉我! \ No newline at end of file diff --git a/source/00_supperthomas/index.rst b/source/00_supperthomas/index.rst index 1289246..8dace04 100644 --- a/source/00_supperthomas/index.rst +++ b/source/00_supperthomas/index.rst @@ -16,5 +16,6 @@ MASTER:supperthomas 11_cppcheck/cppcheck.md 12_gitflow/gitflow.md 13_action/readme.md + 13_action/labeler.md 14_github/github_coderowner.md 15_zephyr/index.md \ No newline at end of file