Proposing a Change ¶

Install the Software Stack ¶

Before working on Symfony, setup a friendly environment with the following software:

• Git;
  ギット;
• PHP version 7.2.5 or above.
  PHP バージョン 7.2.5 以降。

Configure Git ¶

Set up your user information with your real name and a working email address:

1
2

$ git config --global user.name "Your Name"
$ git config --global user.email you@example.com

1

$ git config core.autocrlf

1

$ git config --global core.autocrlf input

Get the Symfony Source Code ¶

Get the Symfony source code:

• Create a GitHub account and sign in;
  GitHub アカウントを作成してサインインします。
• Fork the Symfony repository (click on the "Fork" button);
  Symfony リポジトリをフォークします (「フォーク」ボタンをクリックします)。
• Uncheck the "Copy the X.Y branch only";
  「XY ブランチのみをコピーする」のチェックを外します。
• After the "forking action" has completed, clone your fork locally (this will create a symfony directory):
  「フォークアクション」が完了したら、フォークをローカルにクローンします (これにより symfony ディレクトリが作成されます):

1

$ git clone git@github.com:USERNAME/symfony.git

• Add the upstream repository as a remote:
  アップストリーム リポジトリをリモートとして追加します。

1
2

$ cd symfony
$ git remote add upstream https://github.com/symfony/symfony.git

Check that the current Tests Pass ¶

Now that Symfony is installed, check that all unit tests pass for your environment as explained in the dedicated document.

The License ¶

Before you start, you should be aware that all the code you are going to submit must be released under the MIT license.

Choose the right Branch ¶

Before working on a PR, you must determine on which branch you need to work:

• If you are fixing a bug for an existing feature or want to make a change that falls into the list of acceptable changes in patch versions, pick the oldest concerned maintained branch (you can find them on the Symfony releases page). E.g. if you found a bug introduced in v5.1.10, you need to work on 5.4.
  既存の機能のバグを修正している場合、またはパッチバージョンで許容される変更のリストに入る変更を行いたい場合は、関連する最も古いブランチを選択してください (Symfony リリースページでそれらを見つけることができます)。例えば。 v5.1.10 で導入されたバグを見つけた場合は、5.4 で作業する必要があります。

• 6.2, if you are adding a new feature.

  6.2、新しい機能を追加する場合。

  The only exception is when a new major Symfony version (5.0, 6.0, etc.) comes out every two years. Because of the special development process of those versions, you need to use the previous minor version for the features (e.g. use 4.4 instead of 5.0, use 5.4 instead of 6.0, etc.)

  唯一の例外は、新しいメジャー バージョン (5.0、6.0 など) が 2 年ごとにリリースされる場合です。これらのバージョンの特別な開発プロセスのため、機能には以前のマイナー バージョンを使用する必要があります (たとえば、5.0 の代わりに 4.4 を使用する、6.0 の代わりに 5.4 を使用するなど)。

Create a Topic Branch ¶

Each time you want to work on a PR for a bug or on an enhancement, create a topic branch:

1

$ git checkout -b BRANCH_NAME 6.1

Or, if you want to provide a bug fix for the 4.4 branch, first track the remote 4.4 branch locally:

1

$ git checkout --track origin/4.4

Then create a new branch off the 4.4 branch to work on the bug fix:

1

$ git checkout -b BRANCH_NAME 4.4

The above checkout commands automatically switch the code to the newly created branch (check the branch you are working on with git branch).

Use your Branch in an Existing Project ¶

If you want to test your code in an existing project that uses symfony/symfony or Symfony components, you can use the link utility provided in the Git repository you cloned previously. This tool scans the vendor/ directory of your project, finds Symfony packages it uses, and replaces them by symbolic links to the ones in the Git repository.

1

$ php link /path/to/your/project

Before running the link command, be sure that the dependencies of the project you want to debug are installed by running composer install inside it.

Work on your Pull Request ¶

Work on the code as much as you want and commit as much as you want; but keep in mind the following:

• Read about the Symfony conventions and follow the coding standards (use git diff --check to check for trailing spaces -- also read the tip below);
  Symfony の規則について読み、コーディング標準に従ってください (git diff --check を使用して末尾のスペースをチェックします。以下のヒントもお読みください)。
• Add unit tests to prove that the bug is fixed or that the new feature actually works;
  単体テストを追加して、バグが修正されたこと、または新しい機能が実際に機能することを証明します。
• Try hard to not break backward compatibility (if you must do so, try to provide a compatibility layer to support the old way) -- PRs that break backward compatibility have less chance to be merged;
  後方互換性を壊さないように努力してください (そうしなければならない場合は、古い方法をサポートする互換性レイヤーを提供してみてください)。後方互換性を壊す PR はマージされる可能性が低くなります。
• Do atomic and logically separate commits (use the power of git rebase to have a clean and logical history);
  原子的かつ論理的に分離されたコミットを行います (クリーンで論理的な履歴を持つために git rebase の機能を使用します)。
• Never fix coding standards in some existing code as it makes the code review more difficult;
  コードのレビューがより困難になるため、既存のコードのコーディング標準を修正しないでください。

• Write good commit messages: Start by a short subject line (the first line), followed by a blank line and a more detailed description.

  適切なコミット メッセージを書く: 短い件名 (最初の行) から始めて、空白行と詳細な説明を続けます。

  The subject line should start with the Component, Bridge or Bundle you are working on in square brackets ([DependencyInjection], [FrameworkBundle], ...).

  件名は、角かっこ ([DependencyInjection]、[FrameworkBundle]、...) で作業しているコンポーネント、ブリッジ、またはバンドルで始まる必要があります。

  Then, capitalize the sentence, do not end with a period, and use an imperative verb to start.

  次に、文を大文字にし、ピリオドで終わらせず、命令動詞を使用して始めます。

  Here is a full example of a subject line: [MagicBundle] Add `MagicConfig` that allows configuring things.

  件名の完全な例を次に示します。 [MagicBundle] 設定を可能にする `MagicConfig` を追加します。

Prepare your Pull Request for Submission ¶

When your PR is not about a bug fix (when you add a new feature or change an existing one for instance), it must also include the following:

• An explanation of the changes in the relevant CHANGELOG file(s) (the [BC BREAK] or the [DEPRECATION] prefix must be used when relevant);
  関連する CHANGELOG ファイルの変更の説明 (関連する場合は、[BC BREAK] または [DEPRECATION] プレフィックスを使用する必要があります);
• An explanation on how to upgrade an existing application in the relevant UPGRADE file(s) if the changes break backward compatibility or if you deprecate something that will ultimately break backward compatibility.
  変更によって下位互換性が失われる場合、または最終的に下位互換性が失われるものを廃止する場合に、関連する UPGRADE ファイル内の既存のアプリケーションをアップグレードする方法についての説明。

Rebase your Pull Request ¶

Before submitting your PR, update your branch (needed if it takes you a while to finish your changes):

1
2
3
4
5

$ git checkout 6.1
$ git fetch upstream
$ git merge upstream/6.1
$ git checkout BRANCH_NAME
$ git rebase 6.1

When doing the rebase command, you might have to fix merge conflicts. git status will show you the unmerged files. Resolve all the conflicts, then continue the rebase:

1
2

$ git add ... # add resolved files
$ git rebase --continue

Check that all tests still pass and push your branch remotely:

1

$ git push --force origin BRANCH_NAME

Make a Pull Request ¶

You can now make a pull request on the symfony/symfony GitHub repository.

To ease the core team work, always include the modified components in your pull request message, like in:

1
2

[Yaml] fixed something
[Form] [Validator] [FrameworkBundle] added something

The default pull request description contains a table which you must fill in with the appropriate answers. This ensures that contributions may be reviewed without needless feedback loops and that your contributions can be included into Symfony as quickly as possible.

Some answers to the questions trigger some more requirements:

• If you answer yes to "Bug fix?", check if the bug is already listed in the Symfony issues and reference it/them in "Fixed tickets";
  "Bug fix?" に yes と答えた場合、そのバグが既に Symfony の問題にリストされているかどうかを確認し、"Fixed ticket" でそれ/それらを参照してください。
• If you answer yes to "New feature?", you must submit a pull request to the documentation and reference it under the "Doc PR" section;
  「新機能ですか?」に「はい」と答えた場合は、ドキュメントにプル リクエストを送信し、「Doc PR」セクションで参照する必要があります。
• If you answer yes to "BC breaks?", the PR must contain updates to the relevant CHANGELOG and UPGRADE files;
  「BC break?」に「はい」と答えた場合、PR には関連する CHANGELOG および UPGRADE ファイルへの更新が含まれている必要があります。
• If you answer yes to "Deprecations?", the PR must contain updates to the relevant CHANGELOG and UPGRADE files;
  「Deprecations?」に「はい」と答えた場合、PR には関連する CHANGELOG および UPGRADE ファイルへの更新が含まれている必要があります。
• If you answer no to "Tests pass", you must add an item to a todo-list with the actions that must be done to fix the tests;
  「テストに合格」に「いいえ」と答えた場合は、テストを修正するために実行する必要があるアクションを含む項目を todo リストに追加する必要があります。
• If the "license" is not MIT, just don't submit the pull request as it won't be accepted anyway.
  「ライセンス」が MIT でない場合は、とにかく受け入れられないため、プル リクエストを送信しないでください。

If some of the previous requirements are not met, create a todo-list and add relevant items:

1
2
3

- [ ] fix the tests as they have not been updated yet
- [ ] submit changes to the documentation
- [ ] document the BC breaks

If the code is not finished yet because you don't have time to finish it or because you want early feedback on your work, add an item to todo-list:

1
2

- [ ] finish the code
- [ ] gather feedback for my changes

As long as you have items in the todo-list, please prefix the pull request title with "[WIP]".

In the pull request description, give as much detail as possible about your changes (don't hesitate to give code examples to illustrate your points). If your pull request is about adding a new feature or modifying an existing one, explain the rationale for the changes. The pull request description helps the code review and it serves as a reference when the code is merged (the pull request description and all its associated comments are part of the merge commit message).

In addition to this "code" pull request, you must also send a pull request to the documentation repository to update the documentation when appropriate.

Automated Feedback ¶

There are many automated scripts that will provide feedback on a pull request.

1

$ psalm.phar src/Symfony/Component/Workflow

Automated Tests ¶

A series of automated tests will run when submitting the pull request. These test the code under different conditions, to be sure nothing important is broken. Test failures can be unrelated to your changes. If you think this is the case, you can check if the target branch has the same errors and leave a comment on your PR.

Otherwise, the test failure might be caused by your changes. The following test scenarios run on each change:

PHPUnit / Tests

This job runs on Ubuntu using multiple PHP versions (each in their own job). These jobs run the testsuite just like you would do locally.

このジョブは、複数の PHP バージョン (それぞれが独自のジョブ) を使用して Ubuntu で実行されます。これらのジョブは、ローカルで行う場合と同じようにテストスイートを実行します。

A failure in these jobs often indicates a bug in the code.

これらのジョブの失敗は、多くの場合、コードのバグを示しています。

PHPUnit / Tests (high-deps)

This job checks each package (bridge, bundle or component) in src/ individually by calling composer update and phpunit from inside each package.

このジョブは、各パッケージ内から composer update および phpunit を呼び出して、src/individually 内の各パッケージ (ブリッジ、バンドル、またはコンポーネント) をチェックします。

A failure in this job often indicates a missing package in the composer.json of the failing package (e.g. src/Symfony/Bundle/FrameworkBundle/composer.json).

このジョブの失敗は、多くの場合、失敗したパッケージの composer.json にパッケージが見つからないことを示しています (例: src/Symfony/Bundle/FrameworkBundle/composer.json)。

This job also runs relevant packages using a "flipped" test (indicated by a ^ suffix in the package name). These tests checkout the previous major release (e.g. 4.4 for a pull requests on 5.4) and run the tests with your branch as dependency.

このジョブは、「反転」テスト (パッケージ名の ^ サフィックスで示されます) を使用して、関連するパッケージも実行します。これらのテストは、以前のメジャー リリース (5.4 のプル リクエストの場合は 4.4 など) をチェックアウトし、ブランチを依存関係としてテストを実行します。

A failure in these flipped tests indicate a backwards compatibility break in your changes.

これらの反転テストでの失敗は、変更に後方互換性の問題があることを示しています。

PHPUnit / Tests (low-deps)

This job also checks each package individually, but then uses composer update --prefer-lowest before running the tests.

このジョブも各パッケージを個別にチェックしますが、テストを実行する前にcomposer update --prefer-lowest を使用します。

A failure in this job often indicates a wrong version range or a missing package in the composer.json of the failing package.

このジョブの失敗は、多くの場合、失敗したパッケージの composer.json のバージョン範囲が間違っているか、パッケージが不足していることを示しています。

continuous-integration/appveyor/pr

This job runs on Windows using the x86 architecture and the lowest supported PHP version. All tests first run without extra PHP extensions. Then, all skipped tests are run using all required PHP extensions.

このジョブは、x86 アーキテクチャとサポートされている最も低い PHP バージョンを使用する Windows で実行されます。すべてのテストは、追加の PHP 拡張機能なしで最初に実行されます。次に、スキップされたすべてのテストが、必要なすべての PHP 拡張機能を使用して実行されます。

A failure in this job often indicate that your changes do not support Windows, x86 or PHP with minimal extensions.

このジョブの失敗は、多くの場合、変更が最小の拡張機能を持つ Windows、x86、または PHP をサポートしていないことを示しています。

Integration / Tests

Integration tests require other services (e.g. Redis or RabbitMQ) to run. This job only runs the tests in the integration PHPUnit group.

統合テストでは、他のサービス (Redis や RabbitMQ など) を実行する必要があります。このジョブは、統合 PHPUnit グループのテストのみを実行します。

A failure in this job indicates a bug in the communication with these services.

このジョブの失敗は、これらのサービスとの通信にバグがあることを示しています。

PHPUnit / Tests (experimental)

This job always passes (even with failing tests) and is used by the core team to prepare for the upcoming PHP versions.

このジョブは常に (テストが失敗しても) 成功し、今後の PHP バージョンに備えるためにコア チームによって使用されます。

Rework your Pull Request ¶

Based on the feedback on the pull request, you might need to rework your PR. Before re-submitting the PR, rebase with upstream/5.x or upstream/4.4, don't merge; and force the push to the origin:

1
2

$ git rebase -f upstream/6.1
$ git push --force origin BRANCH_NAME

Moderators earlier asked you to "squash" your commits. This means you will convert many commits to one commit. This is no longer necessary today, because Symfony project uses a proprietary tool which automatically squashes all commits before merging.