如何为 PHP 开源扩展包贡献代码？

介绍

鉴于即将到来的 Hacktoberfest，我想为可能想要专门为 PHP package 做出首次贡献的初学者分享一些技巧。根据我自己的经验，我知道与「常规」（Laravel）应用程序相比，处理包的过程看起来令人生畏。

这篇文章旨在为首次参与开源 PHP 包的贡献者提供一些指导。

步骤 1. 在 GitHub 上 fork 包仓库

例如，假设我们要处理 laravel-medialibrary 包。

首先，在 GitHub 上 fork 包的仓库，因为我们（可能）无权将分支推送到主存储库。分叉将充当我们包的「工作副本」，并作为一个主要的存储库位置来推送包含你的工作的分支。

步骤 2. 克隆你的 fork

将包从 fork 克隆到本地计算机。就个人而言，我有一个文件夹用于存放「应用程序」和「包」。

cd packages

git clone git@github.com:Jhnbrn90/laravel-medialibrary.git .

步骤 3. 在 (Laravel) 项目中引用包

引用应用程序中的克隆包测试所需的功能或错误修复。例如，此应用程序可以是 Laravel 的全新安装，但并非必须如此。

就我个人而言，我总是创建一个名为「hacktober」的新 Laravel 应用程序。

在此应用程序中，你可以通过在应用程序的 composer.json 文件中定义一个自定义的所谓的 repository 来请求 本地 包，而不是通过 Packagist。

将「url」替换为包所在的目录。

{
  "scripts": { ... },

  "repositories": [
    {
      "type": "path",
      "url": "../../packages/laravel-medialibrary"
    }
  ]
}

由于 Composer 使用指定的 repositories 作为后备，你需要在 composer.json 中更新包的名称。否则，它只会引入来自 Packagist 的 Spatie 的最新版本的 laravel-medialibrary。

你可以重命名 composer.json 中的包，如下所示：

{
  "name": "JhnBrn90/laravel-medialibrary",
  ....
}

重要提示： 永远不要提交此更改！
引用 Laravel 应用程序中的包：

composer require JhnBrn90/laravel-medialibrary

这将创建一个指向本地包的符号链接，而不是从 Packagist 安装包。

第 4 步：提交你的工作

你在包中所做的所有更改现在将直接反映在用于测试包的应用程序中。
根据项目的贡献指南中指定的分支为您的功能或错误修复创建一个新分支，通常在 CONTRIBUTING.md 文件中描述。

git checkout -b feature/some-feature

重要：务必将你的更改提交到你 fork 上的除 master 分支以外的分支，因为项目的维护者（或其他人）可能希望在项目更新的时候将更新的部分代码更改推送到你的 master 分支（如果你没有主动从主存储库主动同步更新的内容到你 fork 的仓库的话）。感谢 Caleb (@calebporzio) 推特上的解释：

“是的，如果你从你 fork 的仓库的 master 上创建一个 PR，我无法推送更改。如果它是一个功能分支，我可以拉下 PR 并推送更改。对于添加测试或修复某人的合并冲突等事情很有帮助。否则我必须等他们。

在此分支上提交你的工作，同时尝试通过相关代码段分隔提交。 GitHub Desktop 工具可以轻松地将更改隔离为提交。

步骤 5. 推送你的分支

如果你对当前工作状态感到满意，你可以将分支推送到你自己的存储库分支。

git push --set-upstream origin some-feature

推送你的分支后，GitHub 很可能会提供一个 URL 来直接创建一个新的 PR。或者，你可以通过 GitHub 的 Web 界面创建 PR。

步骤 6. 创建一个新 PR

现在你有了一个包含你工作内容的分支，你可以根据贡献指南从该分支（最常见的是 master 或 develop）创建一个新的 Pull Request 请求。使用「Pull Request」选项卡中的「New Pull Request」 按钮，并确保启用「compare across forks」。这允许你从 fork 上的分支创建 PR 到基本存储库。

写一个好的描述

理想情况下，PR 应该易于理解并明确其意图：

• 为什么你做了/改变了什么
• 它是如何工作的
• 其他人如何测试 PR

有时，在你的 PR 被接受之前，需要进行 PHPUnit 或端到端测试。如果你觉得这很有挑战性，你可以随时询问维护者是否可以稍后将这些添加到你的 PR 中。

一个好的描述示例如下：

关闭 issue #13

做了什么（以及为什么）

一个确认对话框被添加到重置操作按钮，以防止意外重置。

它是如何工作的

• 添加了确认模式的视图
• 向 onClick 操作添加了一个回调，该操作会打开一个新的确认模式

此外，回调接受参数 X 和 Y 能够…，请参见下面的代码示例：

public function showConfirmationDialog($x, $y)
{
  // 添加代码示例以阐明 PR
} 

如何测试

• 单击「重置」，确认模式并断言计数器已重置
• 单击「重置」，取消模式并断言计数器未重置

待办

这些是我不确定的一些事情

• 添加测试：
• 断言单击“取消”不会重置计数器
• 断言单击“确认”会重置计数器

---

总结

我希望建议的工作流程可以帮助首次贡献者自信地为 PHP 包做出贡献。如果你想了解更多关于创建 Laravel 特定包的细节，请务必查看以下资源：

• LaravelPackage.com
• Laravel 包扩展培训
• PHP 扩展包开发课程

---

进阶技巧

配置上游

虽然是可选的，但我建议还将我们从其中派生包的存储库配置为「上游（upstream）」存储库。这使我们可以在稍后阶段从该存储库中提取更改，例如在同时将 PR 合并到 master 中时。

我们可以使用 git remote add 命令添加这个远程仓库地址：

git remote add upstream git@github.com:spatie/laravel-medialibrary.git

当你运行 git remote -v 时，你现在应该会看到两个单独的远程别名：origin 别名指的是你自己的存储库，upstream 别名指的是原始存储库。

用变基（rebase）将你的 PR 更新到最新的代码

在你处理问题或功能时，可能会在你创建 PR 之前合并另一个 PR。在这种情况下，最好在上游存储库中提取 master 的最新更改。

在你当前正在开发的分支中合并 master（或 develop）中的更改，如下所示：

• 确保你的工作分支上的所有更改都已提交并且工作目录是干净的
• 从上游存储库中拉入最新版本的 master：
  • git checkout master
  • git pull upstream master
• 在最新版本的 master 上重新设置你的功能分支：
  • git checkout feature/some-feature
  • git rebase master

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

---

原文地址：https://johnbraun.blog/posts/contributin...

译文地址：https://learnku.com/laravel/t/67963