aeliot / todo-registrar
在问题跟踪器中注册源代码中的 TODO
Requires
- php: ^8.2
- ext-mbstring: *
- ext-tokenizer: *
- lesstif/php-jira-rest-client: ^5.8
- symfony/finder: ^5.4|^6.0|^7.0
Requires (Dev)
- dg/bypass-finals: ^1.7
- enlightn/security-checker: ^2.0
- roave/security-advisories: dev-latest
Suggests
- staabm/phpstan-todo-by: For the monitoring of outdated comments when ticket closed and TODO-comment should be removed
This package is auto-updated.
Last update: 2024-09-28 11:28:51 UTC
README
该脚本从您的 PHP 代码中提取 TODO/FIXME 和其他注释,并在问题跟踪器(如 JIRA)中将其注册为问题。包括所有必要的标签、关联问题等。
动机
有时开发者会在代码中留下笔记,以便不忘记做某事。但他们忘记了。主要原因之一是难以管理。
为什么开发者要在代码中留下注释而不是注册问题?因为方便。你不需要处理问题跟踪器的 UI,也不需要填写很多字段。很多时候,需要注册每个问题,这需要时间。第二个原因是,代码中的注释可以标记必须修改的确切位置。还有许多其他原因。无论为什么他们这么做,他们就是这么做的,并且多年来一直留下这些注释。
有人必须管理它们。
因此,我们需要一个负责注册问题并节省开发者时间的工具。之后,你可以利用所有管理能力来计划解决代码中的缺陷。
此脚本为你完成这些工作。它使用所有必要的参数注册问题。然后将创建的问题的 ID/密钥注入到代码中的注释中。这可以防止创建重复的问题,并帮助快速找到代码中的正确位置。
安装
有几种安装方式
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
使用
- 调用脚本
vendor/bin/todo-registrar
您可以通过传递带有配置路径的选项来传递配置--config=/custom/path/to/config
。否则,它将尝试使用默认路径之一来使用 配置文件。 - 提交更新文件。您可以在 CI 上配置您的管道/作业以提交更新。
CI 集成
主要思想是监控仓库单个分支上的新 TODO,以避免创建重复的问题和合并冲突。该分支应该相当稳定。至少,不应该在它上面直接进行开发。而且应该尽可能靠近开发,以便尽早发现技术债务。简而言之,它被称为 development
。
因此,您必须根据使用的 git 服务器配置您的集成
配置文件
它期望在项目的根目录中添加 .todo-registrar.php
或 .todo-registrar.dist.php
文件。它也可以放在任何其他地方,但您必须在调用脚本时使用选项 --config=/custom/path/to/cofig
指定其路径。配置文件是返回类 \Aeliot\TodoRegistrar\Config
实例的 PHP 文件。
行内配置
脚本支持对每个 TODO 注释的行内配置。它可以帮助灵活地配置创建的问题的不同方面,例如与其他问题的关系、标签、组件等。因此,它成为了一个非常强大的工具。😊
支持的 TODO 标签
默认情况下,它检测 TODO
和 FIXME
。但您可以在配置文件中配置您自己的自定义标签集。它们将不区分大小写地被检测。
支持的注释格式
它检测以 //
和 #
符号开头的单行注释中的 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