Skip to content

Add guideline that changing default values is a BC break #21371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: 6.4
Choose a base branch
from
+23 −7
Open

Add guideline that changing default values is a BC break #21371

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4078cde
Add guideline that changing default values is a BC break
OskarStark Sep 13, 2025
94cca88
Remove CLAUDE.md file
OskarStark Sep 13, 2025
d0802a8
-
OskarStark Sep 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 23 additions & 7 deletions contributing/code/bc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,10 @@ covered by our backward compatibility promise:
+-----------------------------------------------+-----------------------------+
| Add a default value to an argument | Yes |
+-----------------------------------------------+-----------------------------+
| Change default value of an argument | No :ref:`[12] <note-12>` |
+-----------------------------------------------+-----------------------------+
| Remove default value of an argument | No :ref:`[13] <note-13>` |
+-----------------------------------------------+-----------------------------+
Comment on lines +139 to +142
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The BC promise consist of 2 main sections:

  • The first part is "Using Symfony Code", here we explain "if you use an interface/class from Symfony and do this, you can expect your code to keep working"
  • The second part is "Working on Symfony Code", where we explain which changes we and our contributors are allowed to make to Symfony interfaces/classes.

Given this table is part of the first section, we should either revert both of them or change the first to "Yes" and revert the last one.
If you change the default value when implementing an interface, no change in the interface will break your code. So it's OK to change the default value.
And removing a default value while the interface has a default value is not possible in PHP.

| Call a private method (via Reflection) | No |
+-----------------------------------------------+-----------------------------+
| Access a private property (via Reflection) | No |
Expand Down Expand Up @@ -211,7 +215,8 @@ Add argument without a default value No
Add argument with a default value No
Remove argument No :ref:`[3] <note-3>`
Add default value to an argument No
Remove default value of an argument No
Change default value of an argument No :ref:`[12] <note-12>`
Remove default value of an argument No :ref:`[13] <note-13>`
Add type hint to an argument No
Remove type hint of an argument No
Change argument type No
Expand Down Expand Up @@ -264,7 +269,8 @@ Add constructor without mandatory arguments Yes
Add argument with a default value Yes :ref:`[11] <note-11>`
Remove argument No :ref:`[3] <note-3>`
Add default value to an argument Yes
Remove default value of an argument No
Change default value of an argument No :ref:`[12] <note-12>`
Remove default value of an argument No :ref:`[13] <note-13>`
Add type hint to an argument No
Remove type hint of an argument Yes
Change argument type No
Expand All @@ -288,7 +294,7 @@ Move to parent class Yes
Rename argument Yes :ref:`[10] <note-10>`
Remove argument No :ref:`[3] <note-3>`
Add default value to an argument No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Remove default value of an argument No
Remove default value of an argument No :ref:`[13] <note-13>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason not to add "Change default value of an argument No" here and for protected methods below?

Add type hint to an argument No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Remove type hint of an argument No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Change argument type No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Expand All @@ -308,7 +314,7 @@ Move to parent class Yes
Rename argument Yes :ref:`[10] <note-10>`
Remove argument No :ref:`[3] <note-3>`
Add default value to an argument No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Remove default value of an argument No :ref:`[7] <note-7>`
Remove default value of an argument No :ref:`[13] <note-13>` :ref:`[7] <note-7>`
Add type hint to an argument No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Remove type hint of an argument No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Change argument type No :ref:`[7] <note-7>` :ref:`[8] <note-8>`
Expand Down Expand Up @@ -382,7 +388,7 @@ Move to used trait
:ref:`Add argument with a default value <add-argument-public-method>` No
Remove argument No
Add default value to an argument No
Remove default value of an argument No
Remove default value of an argument No :ref:`[13] <note-13>`
Add type hint to an argument No
Remove type hint of an argument No
Change argument type No
Expand All @@ -399,7 +405,7 @@ Move to used trait
:ref:`Add argument with a default value <add-argument-public-method>` No
Remove argument No
Add default value to an argument No
Remove default value of an argument No
Remove default value of an argument No :ref:`[13] <note-13>`
Add type hint to an argument No
Remove type hint of an argument No
Change argument type No
Expand All @@ -414,7 +420,7 @@ Add argument without a default value
Add argument with a default value No
Remove argument No
Add default value to an argument No
Remove default value of an argument No
Remove default value of an argument No :ref:`[13] <note-13>`
Add type hint to an argument No
Remove type hint of an argument No
Change argument type No
Expand Down Expand Up @@ -490,6 +496,16 @@ code when upgrading to newer Symfony versions.

**[11]** Only optional argument(s) of a constructor at last position may be added.

.. _note-12:

**[12]** Changing a default value is a BC break because it changes the behavior
of existing code that relies on the current default value.

.. _note-13:

**[13]** Removing a default value is a BC break because it makes previously
optional arguments required, breaking existing code that doesn't pass all arguments.

Making Code Changes in a Backward Compatible Way
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down