8000 [Review] Added detailed Backwards Compatibility Promise text by webmozart · Pull Request #3439 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

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

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

Merged
merged 39 commits into from
Feb 20, 2014
Merged

[Review] Added detailed Backwards Compatibility Promise text #3439

Changes from 1 commit
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
840073c
Added detailed BC promise text
webmozart Jan 7, 2014
7320ed0
Updated BC promise to be valid as of Symfony 2.3
webmozart Jan 7, 2014
dacd7ce
Rearranged rules to be more easily understandable
webmozart Jan 7, 2014
79ca9f7
Added information about type compatibility
webmozart Jan 8, 2014
0e925cb
Added tables with safe operations
webmozart Jan 8, 2014
44ecf16
Fixed: No parameters must be added (ever) to API class methods
webmozart Jan 8, 2014
afadaab
Changed: The last parameters of a method may be removed
webmozart Jan 8, 2014
345410c
Rearranged safe operations to make more sense
webmozart Jan 8, 2014
a3ad08c
Removed most of the "cannot" statements which are repeated in the tab…
webmozart Jan 8, 2014
31ab2db
Improved wording
webmozart Jan 8, 2014
502ed95
Added: Some breaking changes to unsafe operations are documented in t…
webmozart Jan 8, 2014
4c5a55d
Rearranged page to have different sections for different user bases
webmozart Jan 8, 2014
c6e850d
Language fixes
webmozart Jan 8, 2014
db76288
Fixed headings
webmozart Jan 8, 2014
54fd836
Language improvements
webmozart Jan 8, 2014
00c6ebe
Fixed safety statements
webmozart Jan 8, 2014
efd3911
Added that adding custom properties is not safe
webmozart Jan 8, 2014
dcbe79a
Improved wording
webmozart Jan 9, 2014
af3a645
Added note about requesting `@api` tags
webmozart Jan 9, 2014
be76644
Added information about internal classes and interfaces
webmozart Jan 9, 2014
dfb3e8b
Improved wording
webmozart Jan 9, 2014
6501a35
Added information about changing return types that are classes or int…
webmozart Jan 9, 2014
0c6420f
Added information about changing parameter types
webmozart Jan 9, 2014
69768dd
Improved wording: use -> call, access
webmozart Jan 10, 2014
5a160c5
Added note about deprecated interfaces/classes
webmozart Jan 10, 2014
ef1f021
Added note about test classes
webmozart Jan 10, 2014
6d9edf1
Improved wording: Changed "safe" to "guaranteed"
webmozart Jan 23, 2014
8c6c7bf
Simplified usage description
webmozart Jan 23, 2014
4868452
Added prose about the difference between regular/API classes/interfaces
webmozart Jan 23, 2014
e11335f
Improved the wording of the "Using Symfony" section
webmozart Jan 24, 2014
25443c0
Improved table formatting
webmozart Feb 12, 2014
11bb879
Grammar
webmozart Feb 12, 2014
fd1d912
Typo
webmozart Feb 12, 2014
bdd3c03
Implemented changes suggested by @WouterJ
webmozart Feb 15, 2014
2320906
Extracted duplicated text into _api_tagging.rst.inc
webmozart Feb 15, 2014
90c4de6
Mentioned Semantic Versioning in the introduction
webmozart Feb 20, 2014
be2251c
Implemented @fabpot's comments
webmozart Feb 20, 2014
ce58ee9
Added rules for adding parent interfaces and moving methods/propertie…
webmozart Feb 20, 2014
0717192
Removed useless line break
webmozart Feb 20, 2014
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
8000
Diff view
Prev Previous commit
Next Next commit
Rearranged page to have different sections for different user bases
  • Loading branch information
@webmozart
webmozart committed Jan 8, 2014
commit 4c5a55d6330d8c4a6ed781e8861d92a97bbb2dad
102 changes: 55 additions & 47 deletions contributing/code/bc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,17 @@ the rules listed below.
parts of it if we discover problems or limitations.
Copy link
Member

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.



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:
Expand All @@ -37,17 +43,15 @@ Methods tagged with ``@api`` are treated as if they belonged to an API
interface.


API Interfaces
~~~~~~~~~~~~~~
### API Interfaces

Copy link
Member

Choose a reason for hiding this comment

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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:

Expand All @@ -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:

Expand All @@ -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:
Expand All @@ -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:

Expand All @@ -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:

============================================== ============== ==============
Copy link
Contributor

Choose a reason for hiding this comment

The 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

Copy link
Member

Choose a reason for hiding this comment

The 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

Copy link
Contributor

Choose a reason for hiding this comment

The 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

Copy link
Member

Choose a reason for hiding this comment

The 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 +--+ format)

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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 +--+ format.

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
Expand Down
0