贡献指南

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

在本地设置 Livewire 和 Alpine

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

Fork 和克隆存储库

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

shell

# 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，可以访问存储库页面。

shell

# 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 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 ../../

# 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 @alpinejs/sort @alpinejs/ui

# Build Livewire
npm run build

贡献失败的测试

如果您遇到错误并且不确定如何解决它，特别是考虑到 Livewire 核心的复杂性，您可能想知道从哪里开始。在这种情况下，最简单的方法是贡献一个失败的测试。这样，更有经验的人可以协助识别和修复错误。尽管如此，我们建议您也探索核心代码以更好地了解 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
//...

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

2. 确定测试类型

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

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

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

单元测试应添加到 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" # To run a specific test
vendor/bin/phpunit # To run all tests

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

4. 准备您的 pull request 分支

完成功能或失败测试后，就可以将 Pull Request (PR) 提交到 Livewire 存储库了。首先，确保将更改提交到单独的分支（避免使用 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: 100% (6/6), done.

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

5. 提交您的 pull request

我们快完成了！打开 Web 浏览器并导航到您 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