Submitting a Patch

Install the Software Stack¶

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

• Git;
• PHP version 5.3.3 or above;
• PHPUnit 4.2 or above.

Configure Git¶

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

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

$ git config core.autocrlf

$ git config --global core.autocrlf input

Get the Symfony Source Code¶

Get the Symfony source code:

• Create a GitHub account and sign in;
• Fork the Symfony repository (click on the “Fork” button);
• After the “forking action” has completed, clone your fork locally (this will create a symfony directory):

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

• Add the upstream repository as a remote:

$ cd symfony
$ git remote add upstream git://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 must know that all the patches you are going to submit must be released under the MIT license, unless explicitly specified in your commits.

Choose the right Branch¶

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

• 2.3, if you are fixing a bug for an existing feature (you may have to choose a higher branch if the feature you are fixing was introduced in a later version);
• 2.7, if you are adding a new feature which is backward compatible;
• master, if you are adding a new and backward incompatible feature.

Create a Topic Branch¶

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

$ git checkout -b BRANCH_NAME master

Or, if you want to provide a bugfix for the 2.3 branch, first track the remote 2.3 branch locally:

$ git checkout -t origin/2.3

Then create a new branch off the 2.3 branch to work on the bugfix:

$ git checkout -b BRANCH_NAME 2.3

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

Work on your Patch¶

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);
• 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) – patches that break backward compatibility have less chance to be merged;
• Do atomic and logically separate commits (use the power of git rebase to have a clean and logical history);
• Squash irrelevant commits that are just about fixing coding standards or fixing typos in your own code;
• Never fix coding standards in some existing code as it makes the code review more difficult;
• Write good commit messages (see the tip below).

Prepare your Patch for Submission¶

When your patch 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);
• 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.

Rebase your Patch¶

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

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

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:

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

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

$ 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:

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

The pull request description must include the following checklist at the top to ensure that contributions may be reviewed without needless feedback loops and that your contributions can be included into Symfony as quickly as possible:

| Q             | A
| ------------- | ---
| Bug fix?      | [yes|no]
| New feature?  | [yes|no]
| BC breaks?    | [yes|no]
| Deprecations? | [yes|no]
| Tests pass?   | [yes|no]
| Fixed tickets | [comma separated list of tickets fixed by the PR]
| License       | MIT
| Doc PR        | [The reference to the documentation PR if any]

An example submission could now look as follows:

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #12, #43
| License       | MIT
| Doc PR        | symfony/symfony-docs#123

The whole table must be included (do not remove lines that you think are not relevant). For simple typos, minor changes in the PHPDocs, or changes in translation files, use the shorter version of the check-list:

| Q             | A
| ------------- | ---
| Fixed tickets | [comma separated list of tickets fixed by the PR]
| License       | MIT

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”;
• If you answer yes to “New feature?”, you must submit a pull request to the documentation and reference it under the “Doc PR” section;
• If you answer yes to “BC breaks?”, the patch must contain updates to the relevant CHANGELOG and UPGRADE files;
• If you answer yes to “Deprecations?”, the patch must contain updates to the relevant CHANGELOG and UPGRADE files;
• 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;
• If the “license” is not MIT, just don’t submit the pull request as it won’t be accepted anyway.

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

- [ ] 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:

- [ ] 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 details 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.

Rework your Patch¶

Based on the feedback on the pull request, you might need to rework your patch. Before re-submitting the patch, rebase with upstream/master or upstream/2.3, don’t merge; and force the push to the origin:

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

Often, moderators will ask you to “squash” your commits. This means you will convert many commits to one commit. To do this, use the rebase command:

$ git rebase -i upstream/master
$ git push --force origin BRANCH_NAME

After you type this command, an editor will popup showing a list of commits:

pick 1a31be6 first commit
pick 7fc64b4 second commit
pick 7d33018 third commit

To squash all commits into the first one, remove the word pick before the second and the last commits, and replace it by the word squash or just s. When you save, Git will start rebasing, and if successful, will ask you to edit the commit message, which by default is a listing of the commit messages of all the commits. When you are finished, execute the push command.