README

为 Wikibase 仓库执行约束检查的扩展。

安装

在您的 MediaWiki 安装的 extensions/ 目录中克隆 WikibaseQualityConstraints。

cd .../extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/WikibaseQualityConstraints

安装依赖。最简单的方法是设置 composer-merge-plugin 并在 MediaWiki 基础目录中运行 composer install；或者，您也可以在 WikibaseQualityConstraints 目录中运行 composer install。

加载扩展。

wfLoadExtension( 'WikibaseQualityConstraints' );

运行 php maintenance/update.php --quick。
配置扩展。您可以在 extension.json 中找到配置设置和相关文档。（注意，LocalSettings.php 中的变量名始终以 wg 开头，例如 $wgWBQualityConstraintsClassId 用于 WBQualityConstraintsClassId 设置。）
- 指定用于定义约束的实体的实体 ID。有关自动执行此操作的说明，请参阅“数据导入”部分。
- 如果您有一个或多个 SPARQL 端点，请在 WBQualityConstraintsSparqlEndpoint 中配置主端点，并在 WBQualityConstraintsAdditionalSparqlEndpoints 中配置任何附加端点。
- 或者，为了在不运行完整的 SPARQL 服务器的情况下检查“格式”约束，您可以使用 minisparql 服务器。
运行 php maintenance/run.php WikibaseQualityConstraints:ImportConstraintStatements.php。

客户端脚本

该扩展包括一个客户端脚本，用于检查实体页面上的约束并在语句中显示违规情况。默认情况下，它对所有已登录用户加载；匿名用户可以在网页中通过在 Web 控制台中输入以下代码来加载它

mw.loader.load( 'wikibase.quality.constraints.gadget' );

数据导入

对于本地开发，从 Wikidata 导入一些数据是最简单的。您可以使用 ImportConstraintEntities 维护脚本来完成此操作；它将导入您本地维基尚未存在的所有所需实体，然后打印一个配置片段，您可以将其附加到您的 LocalSettings.php。

# working directory should be the MediaWiki installation folder, i.e. where LocalSettings.php is
php maintenance/run.php WikibaseQualityConstraints:ImportConstraintEntities.php | tee -a LocalSettings.php

（新实体将在作业队列中处理之前不会出现在您维基的最近更改中；如果它没有自动发生，请尝试运行 maintenance/runJobs.php 脚本。）

运行测试

PHP

运行此扩展的测试有两种方法

使用包含的配置文件
```
# from the MediaWiki installation folder
composer phpunit -- -c extensions/WikibaseQualityConstraints/phpunit.xml.dist
```
这会创建测试覆盖率报告（在 tests/coverage/ 和 build/logs/clover.xml 中），因此速度相对较慢。

不使用配置文件

# from the MediaWiki installation folder
composer phpunit:entrypoint extensions/WikibaseQualityConstraints/tests/phpunit/

这会运行测试而不生成覆盖率报告，因此速度要快得多。

JavaScript

您可以通过添加以下内容来运行测试，同时进行代码质量断言的 linting 和其他少量工具

  # from this extension's folder
  npm install
  grunt test

添加新的约束类型

要添加新的约束类型，需要以下步骤

定义约束检查器类。
- 它应该定义在 src/ConstraintCheck/Checker/ 的新文件中，名称与类名相同。它应该在 WikibaseQuality\ConstraintReport\ConstraintCheck\Checker 命名空间中。
- 类名应遵循约束类型名称（英文），以“Checker”结尾。
- 该类必须实现 ConstraintChecker 接口。
- 它应该有至少以下级别的类文档注释
```
/**
 * @author YOUR NAME HERE
 * @license GPL-2.0-or-later
 */
```
- 所需的任何服务（例如Config、EntityLookup等）应作为构造函数参数注入。
- 如果约束有参数，请为它们添加对ConstraintParameterParser的解析支持（在extension.json中添加相关属性的配置设置，并在ConstraintParameterParser中添加解析参数的方法），然后在ConstraintParameterParserTest中添加对这些参数的测试。这应该在一个单独的提交中完成。
定义新的消息（至少为约束类型定义一个违规消息）。
- 在i18n/en.json中定义消息。违规消息应有一个类似于wbqc-violation-message-constraintType的键。
- 在i18n/qqq.json中记录消息。使用相同的信息键，并在en.json中添加消息的位置插入文档（即，en.json和qqq.json应包含相同顺序的信息键）。
为约束类型的项目ID添加配置设置。
- 配置设置在extension.json中定义，作为config对象成员。
- 它应该添加在当前最后的…ConstraintId条目之后。
- 它应该以约束类型项目英文标签命名，格式为WBQualityConstraints…ConstraintId。
- 默认值应该是Wikidata上的项目ID，这样就不需要对Wikidata和导入约束类型项目进行额外配置（参见“数据导入”部分）。
- 描述的第一部分可以从类似的设置中复制，其余部分应包含约束类型的简短描述。
- ID始终可以是公开的（"public": true）。
注册新的约束类型检查器。
- 在ConstraintCheckerServices.php中，添加如下常量：
```
public const …_CHECKER = 'WBQC_…Checker';
```
  在常量列表的末尾。值应为'WBQC_'后跟类名，常量名称应为类名转换为大写并使用下划线分隔。
- 同样在ConstraintCheckerServices.php中，添加如下方法：
```
/**
 * @param MediaWikiServices|null $services
 * @return ConstraintChecker
 */
public static function get…Checker( MediaWikiServices $services = null ) {
	return self::getService( $services, self::…_CHECKER );
}
```
  在类末尾。
- 在ServiceWiring-ConstraintCheckers.php中，将如下新函数添加到服务数组中：
```
ConstraintCheckerServices::…_CHECKER => function( MediaWikiServices $services ) {
	return new …Checker(
    	// injected services
    );
},
```
  。
- 在ServiceWiring.php中，将如下新条目添加到DELEGATING_CONSTRAINT_CHECKER函数中的$checkerMap数组中：
```
$config->get( 'WBQualityConstraints…ConstraintId' )
	=> ConstraintCheckerServices::get…Checker( $services ),
```
  。
- 在ServicesTest.php中，将如下新条目添加到provideConstraintCheckerServiceClasses()中的数组中：
```
[ …Checker::class ],
```
  。
为新的约束检查器添加测试。
- 测试类名称应与检查器类名称相同，并附加后缀Test（例如，…CheckerTest）。
- 测试类应放置在tests/phpunit/Checker/的某个位置，无论是最合适的子目录还是如果没有合适的子目录，则直接在该目录中。（那里的子目录划分本身就值得怀疑，我们可能在未来去掉它。）
- 它应该有至少以下级别的类文档注释
```
/**
 * @covers WikibaseQuality\ConstraintReport\ConstraintCheck\Checker\…Checker
 *
 * @group WikibaseQualityConstraints
 *
 * @author YOUR NAME HERE
 * @license GPL-2.0-or-later
 */
```
- 它应至少包含一个符合约束的测试、一个约束违规测试、一个关于已弃用声明的行为测试，以及一个关于checkConstraintParameters方法的测试。
- 使用ResultAssertions特质的相应方法来检查约束检查结果。
- 使用NewItem和NewStatement构建器来构造测试数据。
- 如果检查器使用Config，请使用DefaultConfig特质。
- 如果约束有参数，请将它们的方法添加到ConstraintParameters特质中，并在测试中使用它。
- 您可以从现有的测试中复制粘贴一个getConstraintMock函数，并调整getConstraintTypeItemId模拟的返回值。（希望我们未来能改进这个功能。）
更新DelegatingConstraintChecker的测试。
- 在DelegatingConstraintCheckerTest中，在addDBData()中的$constraints数组中为您的约束类型添加一个条目。
- constraint_guid应该是P1$后跟一个新的UUID（例如，cat /proc/sys/kernel/random/uuid或journalctl --new-id128）。
- 代码中的pid应设置为1。（不是'1'！)
- constraint_type_qid应设置为$this->getConstraintTypeItemId( '…' )，其中…是WBQualityConstraints…ConstraintId extension.json配置键的…部分。
- constraint_parameters应该是约束参数的有效JSON序列化。如果约束类型没有任何参数，您可以传递{}，否则理想情况下应该在ConstraintParameters特质中有创建参数的方法，以便您可以使用json_encode( $this->…Parameter( … ) )（如果有多个参数，可能需要使用array_merge）。
请让具有grafana-admin访问权限的人更新wikidata-quality板中的“约束类型”面板，以添加新的约束类型。

添加新的允许的实体类型

首先，将项引用添加到extension.json中。例如

 "WBQualityConstraintsMediaInfoId": {
     "value": "Q3898244",
     "description": "The item ID of the 'MediaInfo' item, which represents the 'mediainfo' entity type for 'allowed entity types' constraints.",
     "public": true
 }

下一步将在src/ConstraintCheck/Helper/ConstraintParameterParser.php中执行。应将新的允许实体类型添加到parseEntityTypeItem()方法中的switch/case语句。别忘了把它添加到默认情况中！
为了能够在本地上测试新添加的允许实体类型，请执行“数据导入”部分中描述的步骤。

任务：依赖项更新

NodeJS

您可以通过首先运行npm ci以确保本地依赖项是最新的，然后运行npm outdated来查看哪些依赖项有新版本。

grunt-eslint自25.0.0版本起不再支持“flat”eslint配置文件（即.eslintrc.json），这是由于eslint 9以来的更改（见问题#176）。有关我们eslint 9迁移的进展，请参阅T364065。
grunt-stylelint在版本0.20.0中切换到Stylelint 16+，不再支持stylelint-stylistic，这是stylelint-config-wikimedia所依赖的。请参阅问题#225

PHP

运行composer update和composer outdated --direct将列出任何过时的PHP依赖项。目前没有关于包更新的注释或限制。

wikibase / constraints

维护者

详细信息