Livewire v3 貢献ガイド

貢献ガイド

こんにちは！Livewireの貢献ガイドへようこそ。このガイドでは、新しい機能の提案、失敗するテストの修正、バグの解決を通して、Livewireに貢献する方法を見ていきます。Hi there and welcome to the Livewire contribution guide. In this guide, we are going to take a look at how you can contribute to Livewire by submitting new features, fixing failing tests, or resolving bugs.

LivewireとAlpineをローカルにセットアップするSetting up Livewire and Alpine locally

貢献するには、LivewireとAlpineのリポジトリがローカルマシンにセットアップされていることを確認するのが最も簡単な方法です。これにより、変更を加えたり、テストスイートを簡単に実行したりできます。To contribute, the easiest way is to ensure that the Livewire and Alpine repositories are set up on your local machine. This will allow you to make changes and run the test suite with ease.

リポジトリのフォークとクローンForking and cloning the repositories

まず、リポジトリをフォークしてクローンします。これを行う最も簡単な方法は、GitHub CLIを使用することですが、GitHubのリポジトリページの「Fork」ボタンをクリックして、これらの手順を手動で実行することもできます。To get started, the first step is to fork and clone the repositories. The easiest way to do this is by using the GitHub CLI[https://cli.github.com/], but you can also perform these steps manually by clicking the "Fork" button on the GitHub repository page[https://github.com/livewire/livewire].

# 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がインストールされていることを確認してから、次のコマンドを実行します。手動でフォークしたい場合は、リポジトリページにアクセスしてください。To set up Alpine, make sure you have NPM[https://docs.npmjs.com/downloading-and-installing-node-js-and-npm] installed, and then run the following commands. If you prefer to fork manually, you can visit the repository page[https://github.com/alpinejs/alpine].

# 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

失敗するテストの貢献Contributing a Failing Test

バグに遭遇し、特にLivewireコアの複雑さを考えると、どうすれば解決できるかわからない場合は、どこから始めればよいか迷うかもしれません。そのような場合は、失敗するテストを貢献するのが最も簡単なアプローチです。そうすれば、より経験豊富な人がバグの特定と修正を支援できます。それでも、Livewireがどのように動作するかをより深く理解するために、コアを調べてみることをお勧めします。If you're encountering a bug and are unsure about how to solve it, especially given the complexity of the Livewire core, you might be wondering where to start. In such cases, the easiest approach is to contribute a failing test. This way, someone with more experience can assist in identifying and fixing the bug. Nonetheless, we do recommend that you also explore the core to gain a better understanding of how Livewire operates.

ステップバイステップで見ていきましょう。Let's take a step-by-step approach.

1. テストを追加する場所を決定する1. Determine where to add your test

Livewireコアは、特定のLivewire機能に対応するさまざまなフォルダに分割されています。例：The Livewire core is divided into different folders, each corresponding to specific Livewire features. For example:

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

発生しているバグに関連する機能を見つけてください。適切なフォルダが見つからない場合、またはどれを選択すればよいかわからない場合は、いずれかを選択し、テストを正しい機能セットに配置するのに支援が必要であることをプルリクエストで言及することができます。Try to locate a feature that is related to the bug you are experiencing. If you can't find an appropriate folder or if you're unsure about which one to select, you can simply choose one and mention in your pull request that you require assistance with placing the test in the correct feature set.

2. テストの種類を決定する2. Determine the type of test

Livewireテストスイートは、次の2種類のテストで構成されています。The Livewire test suite consists of two types of tests:

1. Unit tests: これらのテストは、LivewireのPHP実装に焦点を当てています。Unit tests: These tests focus on the PHP implementation of Livewire.
2. Browser tests: これらのテストは、実際のブラウザ内で一連のステップを実行し、正しい結果をアサートします。それらは主にLivewireのJavaScript実装に焦点を当てています。Browser tests: These tests run a series of steps inside a real browser and assert the correct outcome. They mainly focus on the Javascript implementation of Livewire.

どちらの種類のテストを選択すればよいかわからない場合、またはLivewireのテストの作成に慣れていない場合は、ブラウザテストから始めることができます。アプリケーションとブラウザで実行する手順を実装して、バグを再現します。If you're unsure about which type of test to choose or if you're unfamiliar with writing tests for Livewire, you can start with a browser test. Implement the steps you perform in your application and browser to reproduce the bug.

単体テストはUnitTest.phpファイルに追加し、ブラウザテストはBrowserTest.phpに追加する必要があります。これらのファイルのいずれかまたは両方が存在しない場合は、自分で作成できます。Unit tests should be added to the UnitTest.php file, and browser tests should be added to BrowserTest.php. If one or both of these files do not exist, you can create them yourself.

Unit testUnit test

use Tests\TestCase;

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

Browser testBrowser test

use Tests\BrowserTestCase;

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

lightbulb Tip: テストの書き方がわからない？ 既存の単体テストとブラウザテストを調べて、テストの書き方を学ぶことができます。既存のテストをコピーして貼り付けるだけでも、独自のテストを作成するための優れた出発点となります。[!tip] Not sure how to write tests? You can learn a lot by explore existing Unit and Browser tests to learn how tests are written. Even copying and pasting an existing test is a great starting point for writing your own test.

3. プルリクエストブランチの準備3. Preparing your pull request branch

機能または失敗するテストが完了したら、Pull Request (PR) をLivewireリポジトリに送信します。まず、変更を別のブランチにコミットしてください (mainの使用は避けてください)。新しいブランチを作成するには、gitコマンドを使用します。Once you have completed your feature or failing test, it's time to submit your Pull Request (PR) to the Livewire repository. First, ensure that you commit your changes to a separate branch (avoid using main). To create a new branch, you can use the git command:

git checkout -b my-feature

ブランチには任意の名前を付けることができますが、後々のために、機能または失敗するテストを反映するわかりやすい名前を使用すると役立ちます。You can name your branch anything you want, but for future reference, it's helpful to use a descriptive name that reflects your feature or failing test.

次に、変更をブランチにコミットします。git add .を使用してすべての変更をステージングし、git commit -m "Add my feature"を使用して、わかりやすいコミットメッセージとともにすべての変更をコミットします。Next, commit your changes to your branch. You can use git add . to stage all changes and then git commit -m "Add my feature" to commit all changes with a descriptive commit message.

ただし、ブランチは現在、ローカルマシンでのみ使用可能です。Pull Requestを作成するには、git pushを使用してブランチをフォークされたLivewireリポジトリにプッシュする必要があります。However, your branch is currently only available on your local machine. To create a Pull Request, you need to push your branch to your forked Livewire repository using git push.

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. プルリクエストの送信4. Submitting your pull request

もう少しです！Webブラウザを開き、フォークされたLivewireリポジトリ (https://github.com/<your-username>/livewire)に移動します。画面の中央に、新しい通知「my-feature had recent pushes 1 minute ago」と「Compare & pull request」というボタンが表示されます。ボタンをクリックして、プルリクエストフォームを開きます。We're almost there! Open your web browser and navigate to your forked Livewire repository (https://github.com/<your-username>/livewire). In the center of your screen, you will see a new notification: "my-feature had recent pushes 1 minute ago" along with a button that says "Compare & pull request." Click the button to open the pull request form.

フォームに、プルリクエストを説明するタイトルを入力し、説明セクションに進みます。テキスト領域には、事前定義されたテンプレートがすでに含まれています。すべての質問に答えてみてください。In the form, provide a title that describes your pull request and then proceed to the description section. The text area already contains a predefined template. Try to answer every question:

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をクリックしてください🚀 おめでとうございます！初めての貢献に成功しました🎉All set? Click on Create pull request 🚀 Congratulations! You've successfully created your first contribution 🎉

メンテナがPRを確認し、フィードバックを提供したり、変更を要求したりする場合があります。できるだけ早くフィードバックに対応するようにしてください。The maintainers will review your PR and may provide feedback or request changes. Please make an effort to address any feedback as soon as possible.

Livewireへの貢献ありがとうございます！Thank you for contributing to Livewire!