译

如何为开源PHP软件包做贡献

admin PHP 暂无评论 824 浏览

介绍

鉴于即将举行的Hacktoberfest，我想为初学者分享一些技巧，这些初学者可能想专门为PHP 软件包做出第一笔贡献。从我自己的经验来看，与“常规”（Laravel）应用程序相比，在一个程序包上工作可能看起来很艰巨。

这篇文章旨在为初学者贡献一些开源PHP软件包的指导。

步骤1.在GitHub上Fork软件包

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

首先，将包Fork到GitHub上，因为我们（可能）无权将分支推送到主存储库。分支将充当我们软件包的“工作副本”，并在中心位置push包含您的工作的分支。

步骤2.克隆你的Fork

将包fork克隆到本地计算机。我个人有一个单独的文件夹，用于“应用程序”和“程序包”。

将包从你的fork克隆到本地计算机。就我个人而言，我有一个单独的文件夹为"applications"和"packages"。

cd packages

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

步骤3.在（Laravel）项目中Require包

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

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

在这个应用程序中，通过在composer.json文件中定义一个所谓的自定义repository，你可以从本地require包，而不是通过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应用程序中Require该软件包：

composer require JhnBrn90/laravel-medialibrary

这将创建到本地软件包的符号链接，而不是从Packagist安装软件包。

第4步：提交工作

您在软件包中所做的所有更改现在都将直接反映在用于测试软件包的应用程序中。

按照项目贡献准则中的说明，为该功能或错误修复程序创建一个新的分支，通常在CONTRIBUTING.md文件中进行描述。

git checkout -b feature/some-feature

在尝试通过相关代码段分隔提交的同时，在此分支上提交您的工作。用GitHub的桌面工具，可以很容易地将更改分别提交。

步骤5.Push分支

如果您对工作的当前状态感到满意，则可以将分支push到自己的存储库分支中。

git push --set-upstream origin some-feature

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

步骤6.创建一个新的PR

现在您已经有了一个包含工作的分支，您可以根据贡献准则（最常见的是master或develop）向分支创建一个新的拉取请求(pull request)。使用 Pull Requests选项卡中的“New pull request”按钮，并确保启用“compare across forks”。这允许您从fork上的分支创建到基本存储库的 PR。

从头开始创建新的PR

写一个好的描述

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

  • 你为什么要做/改变一些东西
  • 如何运作
  • 别人如何测试PR

有时，需要先进行PHPUnit或端到端测试，然后才能接受PR。如果您发现这一挑战，您可以随时询问维护人员，是否有人可以稍后将其添加到您的PR中。

良好描述的示例如下：

解决问题＃13

做了什么（为什么）

确认对话框已添加到“重置操作”按钮，以防止意外重置。

它是如何工作的

  • 确认modal的视图已添加
  • 回调已添加到onClick操作中，这将打开一个新的确认modal

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

public function showConfirmationDialog($x, $y)
{
  // Add a code example to clarify the PR
}

测试方法

  • 单击“重置”，确认modal并断言计数器已重置
  • 单击“重置”，取消modal并断言计数器未重置

Todo

这些是我不确定的事情

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

摘要

我希望建议的工作流程可以帮助初学者对PHP软件包充满信心。如果您想了解有关创建Laravel特定软件包的详细信息，请确保签出以下资源：

进阶技巧

配置upstream

虽然是可选的，但我建议您也将我们从中分叉软件包的存储库配置为“上游”存储库。这使我们可以在以后阶段从此存储库中获取更改，例如，与此同时，当PR合并到主数据库中时。

While optional, I would advise to also configure the repository where we forked the package from as an "upstream" repository. This allows us to pull in changes from this repository at a later stage, for example when a PR was merged into master in the meantime.

我们可以使用以下git remote add命令添加此远程仓库：

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

运行时git remote -v，您现在应该看到两个单独的远程仓库：“ origin”指的是您自己的存储库，“upstream”指的是原始存储库。

使用最新更改更新（rebase）您的PR

当您处理问题或功能时，可能会在创建您的PR之前将其合并。在这种情况下，最好master在上游存储库中引入最新更改。

While you work on an issue or feature, it might happen that another PR was merged before you created yours. In that case, it might be a good idea to pull in the latest changes on master in the upstream repository.

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

Incorporate changes in master (or develop) in the branch you're currently developing on as follows:

  • 确保工作分支上的所有更改都已提交并且工作目录是干净的
  • Pull in the latest version of master from the upstream repository:
    • git checkout master
    • git pull upstream master
  • Rebase your feature branch on the latest version of master:
    • git checkout feature/some-feature
    • git rebase master

via https://johnbraun.blog/posts/contributing-to-a-PHP-package

推荐：在线生成软件包样板https://laravelpackageboilerplate.com/#/

原创翻译，转载请注明来自lenix的博客，地址https://blog.p2hp.com/archives/7461

最后更新于 2020年9月26日

相关博文

如何为开源PHP软件包做贡献
赏
标签: