Development

HowToContributeToSymfony

You must first sign up to be able to contribute.

How to contribute to symfony

Here's the guidelines on how to contribute to the symfony framework. There are several ways you can help its development:

Requesting assistance

If you're seeking help or assistance on symfony, there are mainly three ways to get some support from the community:

  • By subscribing to the users mailing-list. There will always be plenty of symfony users who will be happy to help you.
  • By registering at and browsing the users forums. There will always be plenty of symfony users who will be happy to help you.
  • By joining the #symfony IRC channel on the Freenode servers and politely ask for help.

Reporting bugs

Bug reports help core team making symfony better. You can report a bug by submitting a new ticket, so developers can review it faster and track the bug reports easily. If you think you've found a security issue, please refer to the dedicated procedure.

First, search the symfony ticketing system to see if your problem has not been reported yet.

Then, double-check the official documentation of the symfony version you use to see if you're not misusing the framework.

Also ask on the users mailing-list or on the #symfony IRC channel if you're not sure your issue is really a bug.

Only then, if your problem definitely looks like a bug, fill a ticket with the most details:

  • Use the short summary field to describe the main goal of your ticket.
  • Select the appropriate type for your ticket:
    • defect: You've found a bug in the source code.
    • documentation: You've found mistakes or typos in the documentation.
    • enhancement: You want to make an enhancement request.
  • Describe the application basic context (OS, PHP version, ...)
  • Provide code examples, use cases and/or steps to reproduce the problem.
  • If you can provide a patch, attach it to the ticket and prefix the subject of the ticket (the short summary field) with [PATCH].
  • Don't forget to select the symfony version you're using, eg. 1.0.15 or 1.1RC1 using the dedicated selectbox. If you don't know which precise version of symfony you're using, just type in a prompt the following command at the root of your project:
    $ php symfony -V
    symfony version 1.1.0-RC1 (/Users/niko/Sites/vendor/symfony11rc1/lib)
    
  • Milestone field should be left blank (untouched) because the fix will be scheduled and included in the milestone by the developers.

Never use the ticket system to ask for help or support. Better use the users mailing-list or the #symfony IRC channel for that purpose.

Reporting security issues

If you find a vulnerability issue on symfony, please do not use the ticketing system to report it, but send it to security at symfony-project.com: it will be forwarded to the symfony core team private mailing-list and quickly qualified. You're more than welcome to attach a patch to your report email, if you can provide one.

If the vulnerability is confirmed, here's what's going to happen:

  1. First you'll receive a confirmation from the core team that the problem has been qualified as a security issue, and you'll be provided a roadmap for when the fix will be available. Obviously, while we'll be working on a patch, please do not reveal it publicly.
  2. When (and only when) the patch will be ready, we'll apply it to all the current unstable and stable branches of symfony.
  3. Then we'll announce it on the official symfony blog and on the user mailing-list, and provide detailed patching and/or upgrade procedure.

Submitting patches

We do love patches, but several rules must be followed to ease their integration in the symfony core:

Coding Standards

Following coding standards is one of the easiest way for everybody to understand everybody's code.

Here's the golden rule: Imitate the existing symfony code.

Never use tabulations in the code. Indentation is done by steps of 2 spaces:

<?php
class sfFoo
{
  public function bar()
  {
    sfCoffee::make();
  }
}

Don't put spaces after an opening parenthesis and before a closing one.

<?php
if ($myVar == getRequestValue($name))    // correct
if ( $myVar == getRequestValue($name) )  // incorrect

Use camelCase, not underscores, for variable, function and method names:

  • Good: function makeCoffee()
  • Bad: function MakeCoffee()
  • Bad: function make_coffee()
  • An exception regarding the latter: use underscores for helper functions name (only for symfony 1.0 stuff).

Use underscores for option/argument/parameter names.

Braces always go on their own line.

Use braces for indicating control structure body regardless of number of statements it contains.

Symfony is written in php5, so every class method or member definition should explicitly declare its visibility using the private, protected or public keywords.

Don't end library files with the usual ?> closing tag. This is because it is not really needed, and because it can create problems in the output if you ever have white space after this tag.

In a function body, return statements should have a blank line prior to it to increase readability.

<?php
function makeCoffee()
{
  if (false !== isSleeping() && false !== hasEnoughCaffeineForToday())
  {
    canMakeCoffee();

    return 1;
  }
  else
  {
    cantMakeCoffee();
  }

  return null;
}

All one line comments should be on their own lines and in this format:

<?php
// space first, with no full stop needed

Avoid evaluating variables within strings, instead opt for concatenation:

<?php
$string = 'something';
$newString = "$string is awesome!";  // bad, not awesome
$newString = $string.' is awesome!'; // better
$newString = sprintf('%s is awesome', $string); // for exception messages and strings with a lot of substitutions

Use lowercase PHP native typed constants: false, true and null. The same goes for array(). At the opposite, always use uppercase strings for user defined constants, like define('MY_CONSTANT', 'foo/bar'). Better, try to always use class constants:

<?php
class sfCoffee
{
  const HAZ_SUGAR = true;
}
var_dump(sfCoffee::HAZ_SUGAR);

To check if a variable is null or not, don't use the is_null() native PHP function:

<?php
if (null !== $coffee)
{
  echo 'I can haz coffee';
}

When comparing a variable to a string, put the string first and use type testing when applicable:

<?php
if (1 === $variable)

Use PHP type hinting in functions and method signatures:

<?php
public function notify(sfEvent $event)
{
  // ...
}

All function and class methods should have their phpdoc own block:

  • All @... statements do not end with a dot.
  • @param lines state the type and the variable name. If the variable can have multiple types, then the mixed type must be used.
  • Ideally @... lines are vertically lined up (using spaces):
    <?php
    /**
     * Notifies all listeners of a given event.
     *
     * @param  sfEvent  $event  A sfEvent instance
     *
     * @return sfEvent          The sfEvent instance
     */
    public function notify(sfEvent $event)
    
    

Patch style

Make sure your code matches the symfony coding standards.

Patch files should always be the result of the svn diff command and have their filename suffixed with the .diff extension. Here's a quick snippet on how to quickly generate a patch file from the modifications you've made to symfony:

$ cd /path/to/symfony
$ svn diff > /tmp/mypatch.diff

When creating patches, always run svn diff from the root directory of the symfony version you're currently working on.

Attach patches to a ticket through Trac, using the Attach file button, and prefix the ticket short summary with [PATCH], like this:

[PATCH] sfWebRequest doesn't handle HTTP PUT method correctly

Please don't put the patch in the ticket description or comment, unless it's a single line patch.

The code required to fix a problem or add a feature is an essential part of a patch, but it is not the only part. A good patch should also include a regression test to validate the behavior that has been fixed (and prevent the problem from arising again).

If the code associated with a patch adds a new feature, or modifies behavior of an existing feature, the patch should also contain documentation.

Commit Procedure

Below are the guidelines if you want to commit something on the symfony repository:

Always start your commit message with list of branches on which it applies in brackets, followed by a past verb and be as verbose as you can.

  • Good: [1.1, 1.2] fixed database configuration didn't apply when used with Propel 1.3
  • Bad: the problem is fixed
  • Bad: repairing memory leak
  • Bad: stuff done

As your commit messages will be readable through the Trac interface, you can use wiki syntax to make them more reader friendly. For example:

[1.3] fixed #1234 - Added yaml database configuration syntax, now you can use:
{{{
propel:
 class:    sfPropelDatabase
   params:
     dsn:  mysql://user:pass@host/dbname
}}}

Limit commits to the most granular change that makes sense. This means, use frequent small commits rather than infrequent large commits. For example, if implementing feature X requires a small change to library Y, first commit the change to library Y, then commit feature X in a separate commit.

If your commit closes an existing ticket in the symfony Trac, end your commit message with the text (fixes #abc), where abc is the number of the ticket your commit fixes. For example:

[1.3] added support for foo (fixes #123)

This syntax will close automatically the referenced ticket in Trac. If your commit closes several tickets, just add them separated by commas:

[1.3] added support for foo (fixes #123, #234)

If your commit references an existing ticket but does not close it, use the refs #abc text snippet, where abc is the number of the ticket your commit references.

If you commit a patch from someone else, include his/her Trac username in the message:

[1.3] added support for foo (fixes #123 - patch from robert.hue)

If your commit closes a ticket and is in a plugin, use the plugin name first between brackets. For example: [sfFooBarPugin] added foobar feature (fixed #1234)

If your commit is about a documentation problem, start your commit message with [doc]. For example: [doc] fixed ukrainian translations in jobeet tutorial

When you have a bug fix patch, always apply it on all the official symfony branches where the bug exists.

Don't forget to change the milestone of the ticket you close.

Before committing a patch, please be sure that it works for the minimum version of PHP needed to run the symfony version you're working on:

  • symfony 1.0 must run on PHP 5.0.0 and up
  • symfony 1.1 must run on PHP 5.1.3 and up
  • symfony 1.2 must run on PHP 5.2.4 and up

Unit and functional tests

Symfony is quite heavily programatically tested, using the bundled lime testing framework. To launch the full test suite, follow these two simple steps:

For symfony 1.2 and older:

  1. Checkout the symfony version you want to test.
  2. Run the php ./test/bin/prove.php script from the command line.
  3. Go for a coffee, as it can take a while for all tests to be run.

for Symfony 1.3 and newer:

  1. Checkout the symfony version you want to test.
  2. Make sure you have php-sqlite module installed and activated
  3. Run the php ./data/bin/symfony symfony:test script from the command line.
  4. No need to grab coffee when debugging test failures. Pass --only-failed to the command and only tests that have failed last time are executed.

If all test pass, you should see a green bar at the bottom of the suite results. If you don't, that means the time to debug has come.

Every symfony release must have all unit and functional tests passing. If you commit new features or correct a bug, please run the test suite to ensure you haven't broken something elsewhere. Never commit if some tests do not pass.

Branch policy

There is no trunk/ in the symfony repository. That's intentional.

The current development versions actually sit in the branches subfolders. These versions are quite stable in fact, but if you need absolute confidence, use tagged versions (the ones which resides in the tags subfolder of the repository). The main advantage regarding branches use is that you just have to periodically run an svn update command to have the latest symfony version, so people should be able to run production sites against the branches/1.0 and branches/1.2 branches at any time.

Developers working on a branch should periodically merge changes from the official branch into the branch. Please merge at least once a week. Every time you merge from the official branch, note the merge and revision numbers in the commit message.

Official releases

Symfony's release numbering works as follows:

Versions are numbered in the form A.B or A.B.C, where:

  • A is the major version number, which is only incremented for major changes to symfony, and these changes are not necessarily backwards-compatible. That is, code you wrote for symfony 1.0 may break when we release symfony 2.0.
  • B is the minor version number, which is incremented for large yet backwards compatible changes. Code written for symfony 1.0 will continue to work under symfony 1.1.
  • C is the micro version number which, is incremented for bug and security fixes. A new micro-release will always be 100% backwards-compatible with the previous micro-release.

In the symfony subversion repository, each release of the framework code will be tagged under the tags folder.

Commit accesses

All commit access requests must be sent at fabien.potencier at symfony-project.com.

Symfony has three main committer level access : full, branch and plugins/documentation.

Full committers

Only the core team has full write access to the whole symfony Subversion repository. Core team members are promoted by the core team itself, regarding these criteria:

  • Implication into the community
  • Quality of contributions
  • Respectfulness to others

Branch committers

If you want to work on one or many specific core features of symfony, you can request the creation of a dedicated branch. You will have to motive for it and won't have any guarantee that we'll handle your request positively.

Plugins and documentation committers

If you have developed a plugin and want to version it in the symfony plugins repository, you can request for a write access on the plugins subfolder.

If you want to help documenting the framework documentation, you can request for a write access on the doc subfolder.

Writing documentation

Here are a few guidelines for the people interested in contributing to the documentation.

Format

The symfony documentation source files are written using the Markdown wiki syntax. This makes them easy to read as text files, and easy to display them in a browser through simple markdown-to-html converters.

This means that when you modify a file of the documentation, you should always check if the Markdown syntax is correct by testing your page in a Markdown renderer.

The symfony framework documentation is primarily written in English, but you can also help to translate it in your own language.

Version

  • The documentation is versioned in a dedicated docs subfolder of the official symfony repository. The file tree structure of this subrepository reflects the actual existing symfony versions, tags and branches included. Please commit your enhancement in the according version documentation repository.
  • As the documentation evolves constantly. Before committing your modifications, always update to the latest version by calling this command in your local documentation checkout directory:
    $ svn update
    

Style

Notice that the documentation never uses *we*, but prefers referring to the reader rather than the author. Please follow this guideline when writing new paragraphs.

All the code chunks, file names, references to objects or other code-related words always have to be declared as code (i.e. enclosed in ticks in the markdown file.)

Translating documentation

A strong effort is currently made by several members of the symfony community to translate parts of the english documentation of the framework into their own locale. If you want to join this effort, check out instructions on the symfony wiki.

Miscellaneous

Credits

Some parts of this page has been inspired by the Django "How to contribute" one, which is really great, as the related framework. Yes, we can say that, too :-)