README

OOUI是一个基于组件的JavaScript UI库。主要特性

• 常用小部件、布局和对话框
• 类、元素和混合，用于创建自定义界面
• 国际化本地化，如支持从右到左（RTL）语言
• 主题化
• 内置图标
• 无障碍功能

它是维基媒体基金会Web产品的标准库，最初是为VisualEditor使用而创建的。

快速开始

库可在npm上获得。要安装

$ npm install oojs-ui

安装后，包含以下脚本和样式以开始使用

<script src="node_modules/jquery/dist/jquery.min.js"></script>
<script src="node_modules/oojs/dist/oojs.min.js"></script>

<script src="node_modules/oojs-ui/dist/oojs-ui.min.js"></script>
<script src="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.js"></script>
<link rel="stylesheet" href="node_modules/oojs-ui/dist/oojs-ui-wikimediaui.min.css">

加载库

尽管分发目录中文件众多，但您通常只需加载以下三个文件

• oojs-ui.js，包含完整库；
• 以下之一：oojs-ui-wikimediaui.css或oojs-ui-apex.css，包含特定主题的样式；以及
• 以下之一：oojs-ui-wikimediaui.js或oojs-ui-apex.js，包含特定主题的代码

您还可以从名为oojs-ui-wikimediaui-icons-*.css或oojs-ui-apex-icons-*.css的文件中加载额外的图标包。

其余文件使您能够只加载整个库的部分。

此外，每个CSS文件都有一个从右到左（RTL）版本可用，如果您的环境不自动根据需要翻转，则可在使用从右到左语言的页面上使用。

问题跟踪器

发现错误或缺失功能？请在我们的问题跟踪器Phabricator中报告！

贡献

我们总是很高兴看到人们贡献补丁。要设置您的开发环境

1. 克隆存储库：$ git clone https://gerrit.wikimedia.org/r/oojs/ui oojs-ui

2. 移动到库目录
   $ cd oojs-ui

3. 安装composer并确保运行composer将执行它（例如，将其添加到POSIX环境中的$PATH）。

4. 安装开发依赖项
   $ npm install

5. 构建库（如果您不需要重新构建PNG，则可以使用grunt quick-build）
   $ grunt build

6. 您可以通过执行以下命令来查看/demos目录中的演示套件
   $ npm run-script demos

7. 您还可以将分发目录中的文件复制到您的项目中。

8. 您可以在根目录中运行php -S localhost:80以启动本地Web服务器。

9. 您可以通过导航到http://localhost/tests/在浏览器中本地运行测试。

我们使用Gerrit进行代码审查，并使用Phabricator跟踪问题。要贡献补丁或加入讨论，您只需要一个开发者帐户。

• 如果您发现了错误，或者想要请求一个功能，请在Phabricator上提交一个工单。
• 要提交您的补丁，请遵循“入门”快速指南。我们尽量在一周内审查补丁。
• 我们自动对JavaScript、PHP、LESS/CSS、Ruby和JSON文件进行代码风格检查和格式化。您可以在推送更改之前，使用npm test和composer test在本地上测试这些更改。在提交之前，应使用svgo --pretty --disable=removeXMLProcInst --disable=cleanupIDs <filename>通过SVGO压缩SVG文件。

库的新版本通常在每周二的上午发布。

社区

获取更新，提出问题，并与维护者及贡献者加入讨论

• 加入wikitech-lWikimedia开发者邮件列表。
• 在irc.libera.chat的#wikimedia-dev上与维护者聊天。
• 在StackOverflow上提问。
• 关注MediaWiki上的文档，以保持最新状态。

版本控制

我们遵循语义化版本控制指南。

版本号将按照以下格式进行编号

<主版本>.<次版本>.<修订号>

发布

先决条件

• 如果您还没有，请创建一个NPM账户
• 验证您是否可以登录您的NPM账户
• 验证您是否被列为oojs-ui包的维护者。如果不是，请让现有的维护者添加您。
• 确保您已设置了两步验证（2FA）。
• 运行npm login并遵循步骤。您可能只需在每个电脑上做一次。如果您不确定是否已经做过，可以运行npm whoami；如果它打印出您的NPM用户名，您已经登录了。
• 克隆mediawiki/vendor仓库：https://gerrit.wikimedia.org/r/admin/repos/mediawiki/vendor,general

准备和提交发布提交

从此仓库的根目录，更新master并检出新的release分支

$ git remote update
$ git checkout -B release -t origin/master

清理安装npm依赖项，更新Composer依赖项，并确保测试通过

$ npm ci && composer update && npm test && composer test

生成包含在此版本中的提交列表

$ git log --format='* %s (%aN)' --no-merges v$(node -e 'console.log(require("./package").version);')...HEAD | grep -v "Localisation updates from" | sort

在History.md中，为这个版本添加一个新的标题和日期。将提交列表复制到新部分，并按顺序排序成五个子部分，忽略任何没有提交的子部分

### Breaking changes
### Deprecations
### Features
### Styles
### Code

生成此版本的Phabricator任务列表。复制生成的列表并保存以备后用。在后续步骤中，您将将其添加到MediaWiki核心提交的提交信息中。

$ git log --pretty=format:%b v$(node -e 'console.log(require("./package").version);')...HEAD | grep Bug: | sort | uniq

更新版本号（在以下命令中，如果您已经做出了破坏性更改，请将'patch'更改为'minor'）

$ npm version patch --git-tag-version=false

提交发布并提交到Gerrit。注意，如果与发布相关的Phabricator任务，您应在运行git review之前编辑提交以添加错误号。

$ git add -u
$ git commit -m "Tag v$(node -e 'console.log(require("./package").version);')"
$ git review

发布标签并推送到NPM

在标签提交合并到此仓库后，推送标签并将其发布到NPM

$ git remote update
$ git checkout origin/master
$ git tag "v$(node -e 'console.log(require("./package").version);')"
$ npm run publish-build && git push --tags && npm publish

更新mediawiki/vendor仓库

在您本地的mediawiki/vendor仓库中，让Composer指向新版本并拉入更新的供应商文件

# Replace 1.2.34 with the version number of the new release
$ composer require oojs/oojs-ui 1.2.34 --no-update
$ composer update --no-dev

然后使用以下提交信息提交更改，将1.2.34替换为新OOUI版本号（例如：https://gerrit.wikimedia.org/r/c/mediawiki/vendor/+/813629）。

$ git add -u
$ git commit

提交信息格式

Update OOUI to v1.2.34

  Release notes: https://gerrit.wikimedia.org/g/oojs/ui/+/v1.2.34/History.md

将此推送到gerrit。注意提交信息中的Change-Id。将其复制并保存以备后用。在更新MediaWiki时，您将需要它用于提交信息中的Depends-On:行。

$ git review
# Show the last commit
$ git show --stat

更新MediaWiki核心仓库

在您的本地MediaWiki核心仓库中，打开composer.json并将oojs/oojs-ui的版本号更新为新版本号。

打开RELEASE-NOTES-1.NN。如果已经有关于OOUI的项目列表，则更新最新的版本号。例如，如果有一个项目列表说“从v1.2.0更新OOUI到v1.2.33”，则更新后者版本号到v1.2.34。如果没有关于OOUI的项目列表，请在Changed external libraries部分添加一个。

打开resources/lib/foreign-resources.yaml。对于OOUI列表，更改version、purl和src URL以使用新版本号。计算新的完整性哈希值。

$ php maintenance/run.php manageForeignResources make-sri ooui
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources make-sri ooui

然后更新OOUI库文件

$ php maintenance/run.php manageForeignResources update ooui
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources update ooui

然后运行以下命令更新foreign-resources.cdx.json

$ php maintenance/run.php manageForeignResources make-cdx
# Or if you're running Docker...
$ docker compose exec mediawiki php maintenance/run.php manageForeignResources make-cdx

然后使用以下提交信息提交更改，将1.2.34替换为新OOUI版本号

$ git add -u
$ git commit

提交信息格式，其中bug列表是您在OOUI标记步骤中生成的列表，Depends-On设置为mediawiki/vendor提交的Change-Id

Update OOUI to v1.2.34

  Release notes: https://gerrit.wikimedia.org/g/oojs/ui/+/v1.2.34/History.md

Bug: T123456
Bug: T234567
Depends-On: I12345678901234567890

然后将其提交推送到gerrit

git review

更新VisualEditor/VisualEditor仓库

在您的本地VisualEditor/VisualEditor仓库中，运行脚本以创建更新本地OOUI副本的提交，并将提交推送到Gerrit

$ ./bin/update-ooui.sh
$ git review