贡献指南

您是视觉学习者吗？
通过我们深入的屏幕录制掌握 Livewire
立即观看

欢迎来到 Livewire 贡献指南。在本指南中，我们将了解如何通过提交新功能、修复失败的测试或解决错误来为 Livewire 做出贡献。

在本地设置 Livewire 和 Alpine

要做出贡献，最简单的方法是确保在本地计算机上设置了 Livewire 和 Alpine 存储库。这将允许您轻松地进行更改和运行测试套件。

分叉和克隆存储库

首先，第一步是分叉和克隆存储库。最简单的方法是使用 GitHub CLI，但您也可以通过单击 GitHub 存储库页面 上的“分叉”按钮手动执行这些步骤。

# Fork and clone Livewire
gh repo fork livewire/livewire --default-branch-only --clone=true --remote=false -- livewire
 
# Switch the working directory to livewire
cd livewire
 
# Install all composer dependencies
composer install
 
# Ensure Dusk is correctly configured
vendor/bin/dusk-updater detect --no-interaction

要设置 Alpine，请确保已安装 NPM，然后运行以下命令。如果您更喜欢手动分叉，可以访问 存储库页面。

# Fork and clone Alpine
gh repo fork alpinejs/alpine --default-branch-only --clone=true --remote=false -- alpine
 
# Switch the working directory to alpine
cd alpine
 
# Install all npm dependencies
npm install
 
# Build all Alpine packages
npm run build
 
# Link all Alpine packages locally
cd alpine/packages/alpinejs && npm link
cd alpine/packages/anchor && npm link
cd alpine/packages/collapse && npm link
cd alpine/packages/csp && npm link
cd alpine/packages/docs && npm link
cd alpine/packages/focus && npm link
cd alpine/packages/history && npm link
cd alpine/packages/intersect && npm link
cd alpine/packages/mask && npm link
cd alpine/packages/morph && npm link
cd alpine/packages/navigate && npm link
cd alpine/packages/persist && npm link
 
# Switch the working directory back to livewire
cd ../livewire
 
# Link all packages
npm link alpinejs @alpinejs/anchor @alpinejs/collapse @alpinejs/csp @alpinejs/docs @alpinejs/focus @alpinejs/history @alpinejs/intersect @alpinejs/mask @alpinejs/morph @alpinejs/navigate @alpinejs/persist
 
# Build Livewire
npm run build

贡献一个失败的测试

如果您遇到错误并且不确定如何解决，特别是考虑到 Livewire 核心的复杂性，您可能想知道从哪里开始。在这种情况下，最简单的方法是提供一个失败的测试。这样，有更多经验的人员可以帮助识别和修复错误。尽管如此，我们还是建议您探索核心，以更好地了解 Livewire 的运作方式。

让我们分步进行。

1. 确定在哪里添加您的测试

Livewire 核心分为不同的文件夹，每个文件夹对应于特定的 Livewire 功能。例如

src/Features/SupportAccessingParent
src/Features/SupportAttributes
src/Features/SupportAutoInjectedAssets
src/Features/SupportBladeAttributes
src/Features/SupportChecksumErrorDebugging
src/Features/SupportComputed
src/Features/SupportConsoleCommands
src/Features/SupportDataBinding
//...

尝试找到与您遇到的错误相关的功能。如果您找不到合适的文件夹，或者不确定选择哪个文件夹，您可以简单地选择一个，并在您的 pull 请求中提到您需要帮助将测试放在正确的功能集中。

2. 确定测试类型

Livewire 测试套件包含两种类型的测试

  1. 单元测试：这些测试关注 Livewire 的 PHP 实现。
  2. 浏览器测试：这些测试在真实浏览器中运行一系列步骤，并断言正确的结果。它们主要关注 Livewire 的 Javascript 实现。

如果您不确定选择哪种类型的测试，或者您不熟悉为 Livewire 编写测试，您可以从浏览器测试开始。实施您在应用程序和浏览器中执行的步骤以重现错误。

单元测试应添加到 UnitTest.php 文件中，浏览器测试应添加到 BrowserTest.php 中。如果这两个文件不存在，您可以自己创建它们。

单元测试

use Tests\TestCase;
 
class UnitTest extends TestCase
{
    /** @test */
    public function livewire_can_run_action(): void
    {
       // ...
    }
}

浏览器测试

use Tests\BrowserTestCase;
 
class BrowserTest extends BrowserTestCase
{
    /** @test */
    public function livewire_can_run_action()
    {
        // ...
    }
}
不确定如何编写测试？

你可以通过探索现有的单元测试和浏览器测试来学习如何编写测试。甚至复制粘贴现有的测试也是编写你自己的测试的一个很好的起点。

3. 准备你的拉取请求分支

一旦你完成了你的功能或失败的测试，就可以向 Livewire 仓库提交你的拉取请求 (PR) 了。首先，确保你将你的更改提交到一个单独的分支（避免使用 main）。要创建一个新分支，你可以使用 git 命令

git checkout -b my-feature

你可以随意给你的分支命名，但为了将来参考，最好使用一个描述性的名称来反映你的功能或失败的测试。

接下来，将你的更改提交到你的分支。你可以使用 git add . 来暂存所有更改，然后使用 git commit -m "Add my feature" 来提交所有更改并附上一个描述性的提交消息。

但是，你的分支目前仅在你的本地机器上可用。要创建一个拉取请求，你需要使用 git push 将你的分支推送到你的已 fork 的 Livewire 仓库。

git push origin my-feature
 
Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 8 threads
Compressing objects: 100% (6/6), done.
 
To github.com:Username/livewire.git
 * [new branch]        my-feature -> my-feature

4. 提交你的拉取请求

我们快完成了！打开你的网络浏览器并导航到你的已 fork 的 Livewire 仓库（https://github.com/<your-username>/livewire）。在你的屏幕中央，你将看到一个新的通知：“my-feature 在 1 分钟前进行了最近的推送”，以及一个写着“比较和拉取请求”的按钮。单击该按钮以打开拉取请求表单。

在表单中，提供一个描述你的拉取请求的标题，然后继续填写描述部分。文本区域中已经包含了一个预定义的模板。尝试回答每个问题

Review the contribution guide first at: https://livewire.laravel.net.cn/docs/contribution-guide
 
1️⃣ Is this something that is wanted/needed? Did you create a discussion about it first?
Yes, you can find the discussion here: https://github.com/livewire/livewire/discussions/999999
 
2️⃣ Did you create a branch for your fix/feature? (Main branch PR's will be closed)
Yes, the branch is named `my-feature`
 
3️⃣ Does it contain multiple, unrelated changes? Please separate the PRs out.
No, the changes are only related to my feature.
 
4️⃣ Does it include tests? (Required)
Yes
 
5️⃣ Please include a thorough description (including small code snippets if possible) of the improvement and reasons why it's useful.
 
These changes will improve memory usage. You can see the benchmark results here:
 
// ...

一切都设置好了吗？单击创建拉取请求 🚀 恭喜！你已经成功创建了你的第一个贡献 🎉

维护人员将审查你的 PR，并可能提供反馈或要求更改。请尽力尽快解决任何反馈。

感谢你对 Livewire 的贡献！