Documented upgrading path for a major version #5155
Conversation
wouterj
force-pushed
the
prepare-major-version
branch
from
b968342
to
dac504a
Compare
wouterj
changed the title
| signatures and public API usages are changed. However, minor versions should | ||
| not contain any backwards compatibility changes. It is made sure that there is | ||
| a so-called *backwards compatibility layer* (or BC layer). This means that the | ||
| old API will still work, hile the new feature is used internally. This BC layer |
There was a problem hiding this comment.
typo: still work, hile the new feature -> still work, while the new feature
|
@wouterj nice work and very important articles. Thanks! |
wouterj
force-pushed
the
prepare-major-version
branch
2 times, most recently
from
c846723
to
8c70f18
Compare
|
Thanks @javiereguiluz! I've applied your suggestions and added the missing screenshot. |
wouterj
changed the title
wouterj
force-pushed
the
prepare-major-version
branch
from
8c70f18
to
f3a130a
Compare
| removed/changed in the future. | ||
|
|
||
| The major version is the only time all existing BC layers are removed. The last | ||
| minor version before a new major version (i.e. 2.7 is the last minor version of |
There was a problem hiding this comment.
2.8 will be the last minor version.
There was a problem hiding this comment.
do you know if this always will be the case? Will the second last minor version always contain the deprecation triggers and is the last minor version always released together with the new major version?
There was a problem hiding this comment.
For now, I would not treat this as an absolute rule.
|
Thanks everyone. I've now updated this PR |
|
We just need to find a consensus on whether or not to do the split (see #5186). |
|
|
||
| Every version of Symfony comes with an UPGRADE file included in the Symfony | ||
| directory that describes these changes. If you follow the instructions in the | ||
| document and update your code accordingly, it should be save to update in the |
There was a problem hiding this comment.
Hah, these are your own words 😉
|
@wouterj I suggested some changes. I don't feel strongly, but my preference is to have an install and an upgrade section, mostly because upgrade is so important (install is actually less important, people will generally go elsewhere - e.g. symfony.com/download - to install) that I don't want to have to hide it under a "Install and Upgrade" section. |
|
Thanks @weaverryan. I've fixed them. I also think we should have a seperate upgrade section. |
|
|
||
| During the lifecycle of a major release, new features are added and method | ||
| signatures and public API usages are changed. However, | ||
| :doc:`minor versions </cookbook/upgrade/minor_version` should not contain any |
There was a problem hiding this comment.
Missing closing angle bracket here after the document name.
|
GREAT work on this Wouter! I shouldn't be, but I can't tell you how excited I am to have these sections :). Thanks! |
This PR was merged into the 2.3 branch. Discussion ---------- Documented upgrading path for a major version | Q | A | --- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | #5059, partially #5111 I feel like there are lots of questions about this topic and nothing has officially been written about it yet. This PR is a first shot at documenting the steps you need to take. I found this one of the hardest things to explain in an easy way. I hope others can improve it a bit :) Todo --- * [x] Add image of toolbar * [x] Add result of PhpUnit bridge Commits ------- 604ccab Fix formatting error 31999db Fixes after review 55fcee9 Applied comments 99c5075 Fix typo 300e8ab Added new recipe on upgrading a major version 2b0aee3 Fix little title case mistake 6a90c9b Created 'upgrade' cookbook section
I feel like there are lots of questions about this topic and nothing has officially been written about it yet. This PR is a first shot at documenting the steps you need to take.
I found this one of the hardest things to explain in an easy way. I hope others can improve it a bit :)
Todo