README

Producer是一个命令行质量保证工具，用于验证并发布您的PHP库包。它支持Git和Mercurial进行版本控制，以及Github、Gitlab和Bitbucket进行远程来源（包括自托管来源）。

安装

Producer与Composer、PHPUnit和PHPDocumentor协同工作。请先安装它们，可以是全局系统的一部分，也可以是您包的一部分。

全局安装

要全局安装Producer，请执行composer global require producer/producer。

请确保将$COMPOSER_HOME/vendor/bin添加到您的$PATH中；有关说明，请参阅此处。

通过在命令行中执行producer来测试安装，以查看一些“帮助”输出。

请记住，您还需要PHPUnit和PHPDocumentor。

包安装

要将Producer包作为您包的开发需求安装，请执行composer require --dev producer/producer。

通过在命令行中执行./vendor/bin/producer来测试安装，以查看一些“帮助”输出。

请记住，您还需要PHPUnit和PHPDocumentor。

配置

在开始之前，您需要创建一个~/.producer/config文件。将以下内容复制并粘贴到您的终端

mkdir ~/.producer

echo "; Github
github_username =
github_token =

; Gitlab
gitlab_token =

; Bitbucket
bitbucket_username =
bitbucket_password =" > ~/.producer/config

然后您可以通过编辑~/.producer/config来输入您的访问凭证，包括但不限于以下内容

• Github个人API令牌,
• Gitlab私人令牌，或
• Bitbucket用户名和密码。

警告：将Bitbucket的用户名和密码以纯文本形式保存并不安全。Bitbucket没有个人API令牌，因此您只能选择“用户名和密码”或者引入一个包含所有依赖项的外部OAuth1库以验证到Bitbucket。后者可能在后续版本中出现。

包配置

在您的包存储库内部，您可以定义一个.producer/config文件，为该特定包设置以下选项之一。

; custom @package docblock value
package = Custom.Name

; custom hostnames for self-hosted origins
github_hostname = example.com
gitlab_hostname = example.net
bitbucket_hostname = example.org

; commands to use for phpunit and phpdoc
[commands]
phpunit = /path/to/phpunit
phpdoc = /path/to/phpdoc

; names for support files
[files]
changes = CHANGES.md
contributing = CONTRIBUTING.md
license = LICENSE.md
phpunit = phpunit.xml.dist
readme = README.md

测试系统：如果您想使用除PHPUnit以外的测试系统，可以设置phpunit = / whatever / you / want。只要测试失败时退出非零，Producer就会与其正确协同工作。是的，将密钥命名为phpunit是短视的；Producer的下一个版本可能会修复这个问题。

入门指南

现在您已安装并配置了Producer，切换到您的库包存储库目录。从那里，您可以调用以下命令

• producer issues将显示远程来源的所有开放问题
• producer phpdoc将检查src/目录中的PHP文档块
• producer validate <version>将验证包以供发布，但实际上不会发布它
• producer release <version>将验证并实际发布包

注意：生成器从存储库读取 .git 或 .hg 配置数据，因此知道您是否使用 Github、Gitlab 或 Bitbucket 作为远程源。

验证

当您验证库包时，生成器将

• 与远程源同步（即从远程源拉取，然后推送任何本地更改，然后检查本地状态以确保所有内容都已提交和推送）
• 验证 composer.json 文件
• 检查信息文件（见下文）以及 phpunit.xml.dist 文件
• 检查许可证文件中是否包含当前年份
• 调用 composer update，运行单元测试，并确保它们清理干净
• 检查 src/ 目录中的 PHP 文档注释是否有效（见下文）
• 检查更改文件是否位于存储库的最新提交中

如果其中任何一个失败，则该包被认为不适合发布。

此外，validate 命令将显示来自远程源的所有开放问题，但这些仅作为提醒，不会被视为无效。

信息文件

生成器希望您在包根目录中拥有这些信息文件

• CHANGES.md，列出发布中的更改；
• CONTRIBUTING.md，描述如何向库贡献力量；
• LICENSE.md，包许可文本；以及，
• README.md，库的介绍。

您可以通过设置适当的 .producer/config 指令来覆盖这些文件名。

文档注释

生成器不会尝试检查 0.*、-dev 或 -alpha 版本的 docblocks。在发布测试版之前，似乎有理由预期代码库尚未准备好进行文档编制。

发布

当您 release 包时，生成器首先将其作为预飞行步骤进行 validate。

然后它将使用 Github 或 Gitlab API 创建发布。在 Bitbucket 的情况下（它没有发布 API），它将在本地标记存储库。

最后，生成器将同步远程源，以便发布在本地表示，并可推送至远程。