-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
[Review] Added detailed Backwards Compatibility Promise text #3439
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.
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
Changes from 1 commit
840073c
7320ed0
dacd7ce
79ca9f7
0e925cb
44ecf16
afadaab
345410c
a3ad08c
31ab2db
502ed95
4c5a55d
c6e850d
db76288
54fd836
00c6ebe
efd3911
dcbe79a
af3a645
be76644
dfb3e8b
6501a35
0c6420f
69768dd
5a160c5
ef1f021
6d9edf1
8c6c7bf
4868452
e11335f
25443c0
11bb879
fd1d912
bdd3c03
2320906
90c4de6
be2251c
ce58ee9
0717192
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
- Loading branch information
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -15,11 +15,17 @@ the rules listed below. | |
parts of it if we discover problems or limitations. | ||
|
||
|
||
Interfaces | ||
---------- | ||
Using Symfony Code | ||
------------------ | ||
|
||
Normal Interfaces | ||
~~~~~~~~~~~~~~~~~ | ||
You are using Symfony in your projects? Stick to the guidelines in this section | ||
in order to guarantee smooth upgrades to all future 2.x versions. | ||
|
||
|
||
Using Our Interfaces | ||
~~~~~~~~~~~~~~~~~~~~ | ||
|
||
### Normal Interfaces | ||
|
||
All interfaces in the ``Symfony`` namespace are **safe for use**. That means | ||
that: | ||
|
@@ -37,17 +43,15 @@ Methods tagged with ``@api`` are treated as if they belonged to an API | |
interface. | ||
|
||
|
||
API Interfaces | ||
~~~~~~~~~~~~~~ | ||
### API Interfaces | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Small formatting nitpick: you have a bunch of double-newlines which should be converted to single-newlines. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I left them in before headings. I'll remove them however. |
||
All interfaces tagged with ``@api`` are also **safe for implementation**. That | ||
means that: | ||
|
||
* You can safely implement the interface. | ||
|
||
|
||
Safe Operations | ||
~~~~~~~~~~~~~~~ | ||
### Safe Operations | ||
|
||
The following table summarizes the safe operations when using our interfaces: | ||
|
||
|
@@ -64,39 +68,10 @@ Add parameter default value Safe Safe | |
============================================== ============== ============== | ||
|
||
|
||
Allowed Changes | ||
~~~~~~~~~~~~~~~ | ||
|
||
This table tells you which changes you are allowed to do when working on the | ||
code of Symfony's interfaces: | ||
|
||
============================================== ============== ============== | ||
Type of Change Normal API | ||
============================================== ============== ============== | ||
Remove entirely No No | ||
Change name or namespace No No | ||
Add parent interface Yes [2]_ No | ||
Remove parent interface No No | ||
**Methods** | ||
Add method Yes [2]_ No | ||
Remove method No No | ||
Change name No No | ||
Add parameter without a default value No No | ||
Add parameter with a default value Yes [2]_ No | ||
Remove parameter Yes [3]_ Yes [3]_ | ||
Add default value to a parameter Yes [2]_ No | ||
Remove default value of a parameter No No | ||
Add type hint to a parameter No No | ||
Remove type hint of a parameter Yes [2]_ No | ||
Change return type Yes [2]_ [4]_ No | ||
============================================== ============== ============== | ||
|
||
|
||
Classes | ||
------- | ||
Using Our Classes | ||
~~~~~~~~~~~~~~~~~ | ||
|
||
Normal Classes | ||
~~~~~~~~~~~~~~ | ||
### Normal Classes | ||
|
||
All classes in the ``Symfony`` namespace are **safe for use**. That means that: | ||
|
||
|
@@ -121,8 +96,7 @@ Properties and methods tagged with ``@api`` are treated as if they belonged | |
to an API class. | ||
|
||
|
||
API Classes | ||
~~~~~~~~~~~ | ||
### API Classes | ||
|
||
All classes tagged with ``@api`` are also **safe for extension**. That means | ||
that: | ||
|
@@ -134,8 +108,7 @@ that: | |
* You can safely override public or protected methods. | ||
|
||
|
||
Safe Operations | ||
~~~~~~~~~~~~~~~ | ||
### Safe Operations | ||
|
||
The following table summarizes the safe operations when using our classes: | ||
|
||
|
@@ -160,11 +133,46 @@ Add parameter default value Safe Safe | |
============================================== ============== ============== | ||
|
||
|
||
Allowed Changes | ||
~~~~~~~~~~~~~~~ | ||
Working on Symfony Code | ||
----------------------- | ||
|
||
Do you want to help us improve Symfony? That's great! However, please stick | ||
to the rules listed below in order to ensure smooth upgrades for our users. | ||
|
||
|
||
Changing Our Interfaces | ||
~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
This table tells you which changes you are allowed to do when working on | ||
Symfony's interfaces: | ||
|
||
============================================== ============== ============== | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. wonder why you changed the format of the table from above to this other format There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It's easier to maintain if the table does not have new line feeds. But we should change the other new tables, to be consistent There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. is that a new adoption on tables in the documentation in general too? interesting i did not know There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't know. We just choose per table which format is best (I think most of them uses the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It was the other way around. I used this format for the above tables initially. But then I introduced cells which span multiple columns above, so I had to switch to the |
||
Type of Change Normal API | ||
============================================== ============== ============== | ||
Remove entirely No No | ||
Change name or namespace No No | ||
Add parent interface Yes [2]_ No | ||
Remove parent interface No No | ||
**Methods** | ||
Add method Yes [2]_ No | ||
Remove method No No | ||
Change name No No | ||
Add parameter without a default value No No | ||
Add parameter with a default value Yes [2]_ No | ||
Remove parameter Yes [3]_ Yes [3]_ | ||
Add default value to a parameter Yes [2]_ No | ||
Remove default value of a parameter No No | ||
Add type hint to a parameter No No | ||
Remove type hint of a parameter Yes [2]_ No | ||
Change return type Yes [2]_ [4]_ No | ||
============================================== ============== ============== | ||
|
||
|
||
Changing Our Classes | ||
~~~~~~~~~~~~~~~~~~~~ | ||
|
||
This table tells you which changes you are allowed to do when working on the | ||
code of Symfony's classes | ||
Symfony's classes | ||
|
||
================================================== ============== ============== | ||
Type of Change Normal API | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be removed. As with any other document, it can be amended if needed.