If you are new to Git, you are highly recommended to read the excellent and
free ProGit book.

Tip

If your IDE creates configuration files inside the project's directory,
you can use global .gitignore file (for all projects) or
.git/info/exclude file (per project) to ignore them. See
GitHub's documentation.

Tip

Windows users: when installing Git, the installer will ask what to do with
line endings, and suggests replacing all LF with CRLF. This is the wrong
setting if you wish to contribute to Symfony! Selecting the as-is method is
your best choice, as Git will convert your line feeds to the ones in the
repository. If you have already installed Git, you can check the value of
this setting by typing:

1

$ git config core.autocrlf

This will return either "false", "input" or "true"; "true" and "false" being
the wrong values. Change it to "input" by typing:

1

$ git config --global core.autocrlf input

Replace --global by --local if you want to set it only for the active
repository

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

2.7, 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 (you may have to choose a higher branch if
the feature you are fixing was introduced in a later version);

master, if you are adding a new feature.

Note

All bug fixes merged into maintenance branches are also merged into more
recent branches on a regular basis. For instance, if you submit a patch
for the 2.7 branch, the patch will also be applied by the core team on
the master branch.

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 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);

Never fix coding standards in some existing code as it makes the code review
more difficult;

Write good commit messages (see the tip below).

Tip

When submitting pull requests, fabbot checks your code
for common typos and verifies that you are using the PHP coding standards
as defined in PSR-1 and PSR-2.

A status is posted below the pull request description with a summary
of any problems it detects or any Travis CI build failures.

Tip

A good commit message is composed of a summary (the first line),
optionally followed by a blank line and a more detailed description. The
summary should start with the Component you are working on in square
brackets ([DependencyInjection], [FrameworkBundle], ...). Use a
verb (fixed ..., added ..., ...) to start the summary and don't
add a period at the end.

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.

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";

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:

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

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.7, don't merge; and force the push to the origin:

1
2

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

Note

When doing a push --force, always specify the branch name explicitly
to avoid messing other branches in the repo (--force tells Git that
you really want to mess with things so do it carefully).

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.