• Naming a Method
• Writing a CHANGELOG Entry
• Deprecating Code
• Removing Deprecated Code
• Naming Commands and Options

Naming a Method

When an object has a "main" many relation with related "things"(objects, parameters, ...), the method names are normalized:

• get()
• set()
• has()
• all()
• replace()
• remove()
• clear()
• isEmpty()
• add()
• register()
• count()
• keys()

The usage of these methods is only allowed when it is clear that thereis a main relation:

• aCookieJar has manyCookie objects;
• a ServiceContainer has many services and many parameters (as servicesis the main relation, the naming convention is used for this relation);
• a ConsoleInput has many arguments and many options. There is no "main"relation, and so the naming convention does not apply.

For many relations where the convention does not apply, the following methodsmust be used instead (whereXXX is the name of the related thing):

Writing a CHANGELOG Entry

When adding a new feature in a minor version or deprecating an existingbehavior, an entry to the relevant CHANGELOG(s) should be added.

New features and deprecations must be described in a file namedCHANGELOG.md that should be at the root directory of the modifiedComponent, Bridge or Bundle.

The file must be written with the Markdown syntax and follow the followingconventions:

• The main title is alwaysCHANGELOG;
• Each entry must be added to a minor version section (like5.3) as a listelement;
• No third level sections are allowed;
• Messages should follow thecommit message conventions:should be short, capitalize the line, do not end with a period, use animperative verb to start the line;
• New entries must be added on top of the list.

Here is a complete example for reference:

1234567

CHANGELOG=========5.3--- *Add`MagicConfig` that allows configuring things

Deprecating Code

From time to time, some classes and/or methods are deprecated in the framework;that happens when a feature implementation cannot be changed because ofbackward compatibility issues, but we still want to propose a "better"alternative. In that case, the old implementation can bedeprecated.

Deprecations must only be introduced on the next minor version of the impactedcomponent (or bundle, or bridge, or contract). They can exceptionally beintroduced on previous supported versions if they are critical.

A new class (or interface, or trait) cannot be introduced as deprecated, orcontain deprecated methods.

A new method cannot be introduced as deprecated.

A feature is marked as deprecated by adding a@deprecated PHPDoc torelevant classes, methods, properties, ...:

123

/** *@deprecated since Symfony 5.1. */

The deprecation message must indicate the version in which the feature was deprecated,and whenever possible, how it was replaced:

123

/** *@deprecated since Symfony 5.1, use Replacement instead. */

When the replacement is in another namespace than the deprecated class, its FQCN must be used:

123

/** *@deprecated since Symfony 5.1, use A\B\Replacement instead. */

A deprecation must also be triggered to help people with the migration(requires thesymfony/deprecation-contracts package):

1

trigger_deprecation('symfony/package-name','5.1','The "%s" class is deprecated, use "%s" instead.', Deprecated::class, Replacement::class);

When deprecating a whole class thetrigger_deprecation() call should be placedafter the use declarations, like in this example fromServiceRouterLoader:

12345678910

namespaceSymfony\Component\Routing\Loader\DependencyInjection;useSymfony\Component\Routing\Loader\ContainerLoader;trigger_deprecation('symfony/routing','4.4','The "%s" class is deprecated, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class);/** *@deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead. */classServiceRouterLoaderextendsObjectRouteLoader

The deprecation must be added to theCHANGELOG.md file of the impacted component:

1234

4.4---*Deprecate the`Deprecated` class, use`Replacement` instead

It must also be added to theUPGRADE.md file of the targeted minor version(UPGRADE-4.4.md in our example):

1234

DependencyInjection------------------- *Deprecate the`Deprecated` class, use`Replacement` instead

Finally, its consequences must be added to theUPGRADE.md file of the next major version(UPGRADE-5.0.md in our example):

1234

DependencyInjection------------------- *Remove the`Deprecated` class, use`Replacement` instead

All these tasks are mandatory and must be done in the same pull request.

Removing Deprecated Code

Removing deprecated code can only be done once every two years, on the nextmajor version of the impacted component (6.0 branch,7.0 branch, etc.).

When removing deprecated code, the consequences of the deprecation must be addedto theCHANGELOG.md file of the impacted component:

1234

5.0--- *Remove the`Deprecated` class, use`Replacement` instead

This task is mandatory and must be done in the same pull request.

Naming Commands and Options

Commands and their options should be named and described using the Englishimperative mood (i.e. 'run' instead of 'runs', 'list' instead of 'lists'). Usingthe imperative mood is concise and consistent with similar command-lineinterfaces (such as Unix man pages).