aeliot/todo-registrar

在问题跟踪器中注册源代码中的 TODO

v1.5.2 2024-09-13 22:11 UTC

README

logo

GitHub Release WFS Code Climate maintainability GitHub Issues or Pull Requests GitHub License

该脚本从您的 PHP 代码中提取 TODO/FIXME 和其他注释,并在问题跟踪器(如 JIRA)中将其注册为问题。包括所有必要的标签、关联问题等。

动机

有时开发者会在代码中留下笔记,以便不忘记做某事。但他们忘记了。主要原因之一是难以管理。

为什么开发者要在代码中留下注释而不是注册问题?因为方便。你不需要处理问题跟踪器的 UI,也不需要填写很多字段。很多时候,需要注册每个问题,这需要时间。第二个原因是,代码中的注释可以标记必须修改的确切位置。还有许多其他原因。无论为什么他们这么做,他们就是这么做的,并且多年来一直留下这些注释。

有人必须管理它们。

因此,我们需要一个负责注册问题并节省开发者时间的工具。之后,你可以利用所有管理能力来计划解决代码中的缺陷。

此脚本为你完成这些工作。它使用所有必要的参数注册问题。然后将创建的问题的 ID/密钥注入到代码中的注释中。这可以防止创建重复的问题,并帮助快速找到代码中的正确位置。

安装

有几种安装方式

  1. Phive
  2. Composer
  3. 直接下载 PHAR

Phive

您可以使用 Phive 安装此软件包。它允许您通过一个控制台命令安装软件包,而无需在 composer 文件中扩展依赖项。

phive install todo-registrar

有时您可能需要更新 PHIVE 的软件包别名数据库。参见 问题 #3。因此,只需调用该命令的控制台命令即可。

phive update-repository-list

使用以下命令升级此软件包

phive update todo-registrar

Composer

您可以使用 Composer 安装此软件包

composer require --dev aeliot/todo-registrar

直接下载 PHAR

直接将 PHAR 下载到项目的根目录或其他您希望的位置。

# Do adjust the URL if you need a release other than the latest
wget -O todo-registrar.phar "https://github.com/Aeliot-Tm/todo-registrar/releases/latest/download/todo-registrar.phar"
wget -O todo-registrar.phar.asc "https://github.com/Aeliot-Tm/todo-registrar/releases/latest/download/todo-registrar.phar.asc"

# Check that the signature matches
gpg --verify todo-registrar.phar.asc todo-registrar.phar

# Check the issuer (the ID can also be found from the previous command)
gpg --keyserver hkps://keys.openpgp.org --recv-keys 47DB2BEBFFE7CF39CD0E91FB1BAD6A09DE0F2DED

rm todo-registrar.phar.asc
chmod +x todo-registrar.phar

使用

  1. 调用脚本
    vendor/bin/todo-registrar
    您可以通过传递带有配置路径的选项来传递配置 --config=/custom/path/to/config。否则,它将尝试使用默认路径之一来使用 配置文件
  2. 提交更新文件。您可以在 CI 上配置您的管道/作业以提交更新。

CI 集成

主要思想是监控仓库单个分支上的新 TODO,以避免创建重复的问题和合并冲突。该分支应该相当稳定。至少,不应该在它上面直接进行开发。而且应该尽可能靠近开发,以便尽早发现技术债务。简而言之,它被称为 development

因此,您必须根据使用的 git 服务器配置您的集成

  1. GitLab 管道

配置文件

它期望在项目的根目录中添加 .todo-registrar.php.todo-registrar.dist.php 文件。它也可以放在任何其他地方,但您必须在调用脚本时使用选项 --config=/custom/path/to/cofig 指定其路径。配置文件是返回类 \Aeliot\TodoRegistrar\Config 实例的 PHP 文件。

查看有关配置的完整文档

行内配置

脚本支持对每个 TODO 注释的行内配置。它可以帮助灵活地配置创建的问题的不同方面,例如与其他问题的关系、标签、组件等。因此,它成为了一个非常强大的工具。😊

查看关于行内配置的文档

支持的 TODO 标签

默认情况下,它检测 TODOFIXME。但您可以在配置文件中配置您自己的自定义标签集。它们将不区分大小写地被检测。

支持的注释格式

它检测以 //# 符号开头的单行注释中的 TODO 标签以及多行注释 /* ... */ 和 phpDoc /** ... **/

注释可以有不同的格式

// TODO: comment summary
// TODO comment summary
// TODO@assigne: comment summary

/**
 * TODO: XX-001 comment summary
 *       with some complex description
 */

以及其他。请参阅所有支持的格式

支持的 Issue Trackers

目前,todo-registrar 支持以下 Issue Trackers

文章

RU: https://habr.com/ru/articles/832994/