为 Joomla！框架做出贡献

存储库结构

截至 2017 年 6 月，Joomla！框架 GitHub 组织 中各个存储库的结构通常相同。

分支

大多数存储库有两个分支代表两个主要框架版本；1.x 和 2.0。除以下注明例外情况外，master 分支代表稳定的 1.x 分支，2.0-dev 分支代表即将发布的 2.0 版本。

• Crypt 包使用 master 分支用于 2.0 版本，使用 1.x-dev 分支用于 1.x 版本
• Log 包没有 2.0 分支，因为该包已弃用，而框架 2.0 版本的开发工作已经开始
• Console、Preload 和 Renderer 包不属于框架 1.x，因此它们的 master 分支代表 2.0 版本

已弃用的包

几个包已经弃用，并且在框架 2.0 版本中不再受支持。除非另有说明，否则一直有正在进行的工作来更新框架 2.0 版本的所有包，包括内部重构，但是由于这些包现已弃用，因此它们的 2.0-dev 分支应被视为已废弃。

• Cache - 相反使用任何 PSR-6 或 PSR-16 兼容包
• Compat
• Date - 相反使用 Carbon 库
• Facebook
• Google
• Image
• LDAP - 相反使用 Symfony LDAP 组件
• LinkedIn
• Log - 相反使用任何 PSR-3 兼容包
• OpenStreetMap
• Twitter

已废弃的包

以下是已弃用且不再受框架工作组和 Joomla！项目支持的包。它们各自的存储库处于只读状态，并且所有维护都已停止。

• DateTime - 相反使用 Carbon 库
• Form

文件结构

Joomla！框架包符合 PSR-4，并遵循通用的文件系统结构。

• .github - GitHub 存储库元数据（贡献指南、问题和请求模板）
• .travis - 适用于 Travis-CI 平台的配置文件
• docs - 作为框架 2.0 版本的一部分，已向每个包添加文档；1.x 分支中不存在该目录
• src - 包的生成代码
• tests - 该包的测试套件

注意由于向 PSR-4 迁移的后向兼容性影响，Crypt 1.x 分支仍然为 PSR-0 支持而设计，因此该分支拥有略微不同的代码库结构。此外，Session 软件包的 1.x 分支未迁移到 PSR-4 并且仍在遵循 PSR-0 结构。

问题/拉取请求

每个软件包的代码库在 GitHub 中通过问题跟踪和拉取请求来管理。所有框架的软件包在 Joomla! Framework 组织中进行列示。有关如何分叉代码库以及开始为 Joomla! Framework 做贡献的文档，可以访问 https://help.github.com/articles/fork-a-repo。

所有提交的贡献都将接受审查并考虑是否纳入框架，但在被接受之前，我们要求您遵循以下简单的准则

• 版本化
• 编码标准
• 单元测试
• 文档

请耐心等待，因为并非所有项目都会立即接受 框架团队 的测试或审查。同时，请接受对框架中您所做更改的反馈。维护团队和其他社区成员可能会提出建议，或询问您的更改的内容。这是审查流程的一部分，有助于每个人了解所发生的情况、发生的原因并潜在优化您的代码。

版本化

当您添加新的类、属性或方法时，请在 Docblocks 中的 @since 标签中使用 __DEPLOY_VERSION__。我们将用更改的实际版本替换该标记。

编码标准

所有提交的代码必须符合 Joomla! 编码标准。此标准记录在 https://developer.joomla.net.cn/coding-standards.html 中。有一个称为 PHP_CodeSniffer 的工具，可用于针对 Joomla! 编码标准验证您的代码。

安装和使用

框架代码库使用 Joomla! 编码标准的 2.x 版本，而该版本基于 PHP_CodeSniffer 的 2.x 分支。在进行 composer install 的过程中会安装 PHP_CodeSniffer，在克隆软件包的 git 代码库时这非常有用。请参阅 https://github.com/squizlabs/PHP_CodeSniffer 了解更多有关 PHP_CodeSniffer 的文档。

一旦 PHP_CodeSniffer 安装完毕并且 Joomla! 编码标准已下载，你就可以在标准中检查你的代码。确切的要运行的命令将根据是存储库使用基础定义还是由于该包中的规则豁免而具有自定义规则集而有所不同，因此我们建议从包的.travis.yml 文件中复制命令。

IDE 支持

一些编辑器支持 PHP_CodeSniffer 作为插件或内置功能。这样你就可以直接在编辑器中查看你的代码是否符合 Joomla! 标准。你可以从该存储库中获取许多编辑器的配置文件：https://github.com/joomla/coding-standards/tree/master/Joomla/IDE。通过 Zip 按钮下载存储库内容，并导入适当的.xml 文件到你的编辑器中。

单元测试

不管你的请求是错误修复还是向框架引入新的类或方法，都要包含单元测试。我们理解，并不是所有的提交请求用户都会熟练掌握 PHPUnit。维护人员和整个社区都是有帮助的团队，可以帮助你编写测试。PHPUnit 和任何额外的测试依赖都会作为一个composer install 的一部分安装，当你在克隆一个包的 Git 存储库时，它会非常有用。请参阅 https://phpunit.de/manual/current/en/index.html。了解 PHPUnit 完整文档。

文档

对于框架 1.x 发布，每个包的文档都可以在存储库根目录中的README.md 文件中找到。从 2.0 开始，每个存储库都有一个专门的docs 目录。

docs 目录结构至少使用以下格式

• classes - 此目录包含有关包的类、接口和特性的文档，包括对象的用途摘要和示例用法
• index.md - 当包文档集成到此站点时，这将用作导航菜单
• overview.md - 这是包及其用法的概述
• v1-to-v2-update.md - 在从 1.x 迁移到 2.0 时，此文件将突出显示每个包中的向后兼容性破坏性更改

文档文件使用 带 GitHub 风味的 Markdown。为现有包提供新功能时，请将新功能的注释添加到你所变更的包中现有的README.md 文件或将新文件添加到docs 目录（根据你变更的提交分支）。在提交新包时，你的请求中将需要一个README.md 文件形式的文档。包文档应该解释开发人员应该如何开始使用包中的代码。文档应该解释类、接口和/或特性，并提供几个简单的示例。