10000 Documented upgrading path for a major version by wouterj · Pull Request #5155 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Documented upgrading path for a major version #5155

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 7 commits into from
May 25, 2015
Merged

Documented upgrading path for a major version #5155

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6a90c9b
Created 'upgrade' cookbook section
wouterj Mar 10, 2015
2b0aee3
Fix little title case mistake
wouterj Mar 10, 2015
300e8ab
Added new recipe on upgrading a major version
wouterj Mar 10, 2015
99c5075
Fix typo
wouterj Apr 14, 2015
55fcee9
Applied comments
wouterj May 23, 2015
31999db
Fixes after review
wouterj May 24, 2015
604ccab
Fix formatting error
wouterj May 25, 2015
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
Prev Previous commit
Next Next commit
Applied comments
  • Loading branch information
@wouterj
wouterj committed May 23, 2015
commit 55fcee9a898db5ee8ee382a235a97f9ed1738b67
2 changes: 1 addition & 1 deletion cookbook/upgrade/_update_all_packages.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ this safely by running:

.. caution::

Beware, if you have some bad `version constraints`_ in your
Beware, if you have some unspecific `version constraints`_ in your
``composer.json`` (e.g. ``dev-master``), this could upgrade some
non-Symfony libraries to new versions that contain backwards-compatibility
breaking changes.
Expand Down
10 changes: 6 additions & 4 deletions cookbook/upgrade/major_version.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,12 @@ old API will still work, while the new feature is used internally. This BC
layer is then marked as *deprecated*, indicating that it will be
removed/changed in the future.
Copy link
Member

Choose a reason for hiding this comment

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

I think this is more technical than we need to be. The important thing is that your old code still works, but is deprecated. Perhaps (starting right after "compatibility changes.")

To accomplish this, the "old" (e.g. functions, classes, etc) code still works, but is marked
as *deprecated*, indicating that it will be removed/changed in the future and that you
should stop using it.


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
the 2 releases, 3.0 is the next version) will trigger deprecation notices when a
BC layer is used.
The major version is the only time all existing BC layers are removed. However,
if you make sure you've fixed all deprecated usages in the last version of the
previous major version, you should be able to upgrade to the new major version
without problems. To help you with this, the last minor releases will trigger
deprecated notices. For example, 2.7 and 2.8 trigger deprecated notices and if
you do not have any notice while using 2.8, you can savely upgrade to 3.0.
Copy link
Member

Choose a reason for hiding this comment

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

A slightly different suggestion, please mix and match - this stuff is just very important (which is why I'm so glad you wrote all this):

When the major version is released (e.g. 3.0.0), all deprecated features and functionality
are removed. So, as long as you've updated your code to stop using these deprecated
features in the last version before the major (e.g. 2.8.*), you should be able to upgrade
without a problem.

To help with this, the last minor releases will trigger deprecation notices. For example, Symfony
2.7 and 2.8 trigger deprecated notices that you can see in the web debug toolbar. When visiting
your application...


When visiting your application in the
:doc:`dev environment </cookbook/configuration/environments>` in your browser,
Expand Down
2 changes: 1 addition & 1 deletion cookbook/upgrade/minor_version.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Next, use Composer to download new versions of the libraries:

.. _`upgrade-minor-symfony-code`:

2) Updating Your Code to Work with the new Version
2) Updating your Code to Work with the new Version
--------------------------------------------------

In theory, you should be done! However, you *may* need to make a few changes
Expand Down
0