贡献指南

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

在本地设置 Livewire 和 Alpine

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

Fork 和克隆仓库

首先，第一步是 fork 和克隆仓库。最简单的方法是使用 GitHub CLI，但您也可以通过点击 GitHub 仓库页面上的 "Fork" 按钮来手动执行这些步骤。

shell

# Fork 和克隆 Livewire
gh repo fork livewire/livewire --default-branch-only --clone=true --remote=false -- livewire

# 切换工作目录到 livewire
cd livewire

# 安装所有 composer 依赖
composer install

# 确保 Dusk 正确配置
vendor/bin/dusk-updater detect --no-interaction

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

shell

# Fork 和克隆 Alpine
gh repo fork alpinejs/alpine --default-branch-only --clone=true --remote=false -- alpine

# 切换工作目录到 alpine
cd alpine

# 安装所有 npm 依赖
npm install

# 构建所有 Alpine 包
npm run build

# 在本地链接所有 Alpine 包
cd packages/alpinejs && npm link && cd ../../
cd packages/anchor && npm link && cd ../../
cd packages/collapse && npm link && cd ../../
cd packages/csp && npm link && cd ../../
cd packages/docs && npm link && cd ../../
cd packages/focus && npm link && cd ../../
cd packages/history && npm link && cd ../../
cd packages/intersect && npm link && cd ../../
cd packages/mask && npm link && cd ../../
cd packages/morph && npm link && cd ../../
cd packages/navigate && npm link && cd ../../
cd packages/persist && npm link && cd ../../
cd packages/sort && npm link && cd ../../
cd packages/ui && npm link && cd ../../

# 切换工作目录回 livewire
cd ../livewire

# 链接所有包
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 @alpinejs/sort @alpinejs/ui

# 构建 Livewire
npm run build

贡献失败的测试

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

让我们采取循序渐进的方法。

1. 确定在哪里添加测试

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

shell

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

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

2. 确定测试类型

Livewire 测试套件由两种类型的测试组成：

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

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

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

单元测试

php

use Tests\TestCase;

class UnitTest extends TestCase
{
    public function test_livewire_can_run_action(): void
    {
       // ...
    }
}

浏览器测试

php

use Tests\BrowserTestCase;

class BrowserTest extends BrowserTestCase
{
    public function test_livewire_can_run_action()
    {
        // ...
    }
}

不确定如何编写测试？

您可以通过探索现有的单元测试和浏览器测试来学习如何编写测试。即使复制粘贴现有测试也是编写自己测试的良好起点。

3. 运行测试

在提交 pull request 之前，请确保您的测试通过。您可以通过运行以下命令之一来完成：

shell

vendor/bin/phpunit --filter "test_can_make_method_a_computed" # 运行特定测试
vendor/bin/phpunit # 运行所有测试

默认情况下，浏览器测试将在有头模式下运行。如果您想在无头模式下运行它们，可以在 Livewire 仓库的根目录中创建一个 .env 文件并添加 DUSK_HEADLESS_DISABLED=false。

4. 准备您的 pull request 分支

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

shell

git checkout -b my-feature

您可以随意命名您的分支，但为了将来参考，使用反映您的功能或失败测试的描述性名称会很有帮助。

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

但是，您的分支目前仅在本地机器上可用。要创建 Pull Request，您需要使用 git push 将分支推送到您 fork 的 Livewire 仓库。

shell

git push origin my-feature

Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 8 threads
Compressing objects: (6/6), done.

To github.com:Username/livewire.git
 * [new branch]        my-feature -> my-feature

5. 提交您的 pull request

我们快完成了！打开您的网络浏览器并导航到您 fork 的 Livewire 仓库（https://github.com/<your-username>/livewire）。在屏幕中央，您将看到一个新通知："my-feature had recent pushes 1 minute ago"，以及一个显示 "Compare & pull request" 的按钮。点击该按钮打开 pull request 表单。

在表单中，提供一个描述您的 pull request 的标题，然后继续到描述部分。文本区域已经包含一个预定义的模板。尝试回答每个问题：

Review the contribution guide first at: https://livewire.laravel.com/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:

// ...

都准备好了吗？点击 Create pull request 🚀 恭喜！您已成功创建了您的第一个贡献 🎉

维护者将审查您的 PR，并可能提供反馈或请求更改。请尽快解决任何反馈。

感谢您为 Livewire 做出贡献！

贡献指南 ​

在本地设置 Livewire 和 Alpine ​

Fork 和克隆仓库 ​

贡献失败的测试 ​

1. 确定在哪里添加测试 ​

2. 确定测试类型 ​

3. 运行测试 ​

4. 准备您的 pull request 分支 ​

5. 提交您的 pull request ​

贡献指南

在本地设置 Livewire 和 Alpine

Fork 和克隆仓库

贡献失败的测试

1. 确定在哪里添加测试

2. 确定测试类型

3. 运行测试

4. 准备您的 pull request 分支

5. 提交您的 pull request