Skip to content

Commit 4895ade

Browse files
weaverryanweaverryan
committed
feature #5186 Added a new article about using/installing unstable Symfony versions (javiereguiluz)
This PR was merged into the 2.3 branch. Discussion ---------- Added a new article about using/installing unstable Symfony versions | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | - In addition to the new article, I propose to move the existing `upgrading.rst` article to the new "Installing and Upgrading" section. New articles related to this topic will be added soon. I plan to add at least two articles: * How to install Symfony with Composer (this will allow us to simplify installation instructions across the documentation and just recommend to use the installer). * How to install Symfony in a Subdirectory (it's not uncommon to have to execute Symfony apps in URLs such as example.com/my-symfony-app/ It's not hard, but at least you have to configure the `router.request_context.base_url` config option, which I think is documented nowhere). Commits ------- 8e8fad2 Removed some wrong labels 1378ec9 Added a note about the Symfony Upgrading Guide 224c380 Fixed a lot of issues pointed by Ryan d5f3d82 Minor improvement in a command 038caa5 Fixed minor issues bae8043 Fixed the beta version constraints a9fee2f Fixed a link to an internal document caff8d2 Minor rewording e1f621e Added a new entry in the redirection_map 724c17f Simplified instructions 6d6303c Fixed a minor error in some index file 719e52c Added the missing file extension 2722933 Fixed articles links df22b75 Fixed typo: "inestable" -> "unstable" 402f5d4 Added a new articule about using/installing inestable Symfony versions
2 parents bf18f16 + 8e8fad2 commit 4895ade

File tree

6 files changed

+232
-0
lines changed

6 files changed

+232
-0
lines changed

‎cookbook/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ The Cookbook
1818
event_dispatcher/index
1919
form/index
2020
frontend/index
21+
install/index
2122
logging/index
2223
profiler/index
2324
request/index

‎cookbook/install/index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Install and Upgrade
2+
===================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
upgrading
8+
unstable_versions

‎cookbook/install/unstable_versions.rst‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
How to Install or Upgrade to the Latest, Unreleased Symfony Version
2+
===================================================================
3+
4+
In this article, you'll learn how to install and use new Symfony versions before
5+
they are released as stable versions.
6+
7+
Creating a New Project Based on an Unstable Symfony Version
8+
-----------------------------------------------------------
9+
10+
Suppose that Symfony 2.7 version hasn't been released yet and you want to create
11+
a new project to test its features. First, :doc:`install the Composer </cookbook/composer>`
12+
package manager. Then, open a command console, enter your project's directory and
13+
execute the following command:
14+
15+
.. code-block:: bash
16+
17+
$ composer create-project symfony/framework-standard-edition my_project "2.7.*" --stability=dev
18+
19+
Once the command finishes its execution, you'll have a new Symfony project created
20+
in the ``my_project/`` directory and based on the most recent code found in the
21+
``2.7`` branch.
22+
23+
If you want to test a beta version, use ``beta`` as the value of the ``stability``
24+
option:
25+
26+
.. code-block:: bash
27+
28+
$ composer create-project symfony/framework-standard-edition my_project "2.7.*" --stability=beta
29+
30+
Upgrading your Project to an Unstable Symfony Version
31+
-----------------------------------------------------
32+
33+
Suppose again that Symfony 2.7 hasn't been released yet and you want to upgrade
34+
an existing application to test that your project works with it.
35+
36+
First, open the ``composer.json`` file located in the root directory of your
37+
project. Then, edit the value of the version defined for the ``symfony/symfony``
38+
dependency as follows:
39+
40+
.. code-block:: json
41+
42+
{
43+
"require": {
44+
// ...
45+
"symfony/symfony" : "2.7.*@dev"
46+
}
47+
}
48+
49+
Finally, open a command console, enter your project directory and execute the
50+
following command to update your project dependencies:
51+
52+
.. code-block:: bash
53+
54+
$ composer update symfony/symfony
55+
56+
If you prefer to test a Symfony beta version, replace the ``"2.7.*@dev"`` constraint
57+
by ``"2.7.0-beta1"`` to install a specific beta number or ``2.7.*@beta`` to get
58+
the most recent beta version.
59+
60+
After upgrading the Symfony version, read the :doc:`Symfony Upgrading Guide </cookbook/upgrade/index>`
61+
to learn how you should proceed to update your application's code in case the new
62+
Symfony version has deprecated some of its features.
63+
64+
.. tip::
65+
66+
If you use Git to manage the project's code, it's a good practice to create
67+
a new branch to test the new Symfony version. This solution avoids introducing
68+
any issue in your application and allows you to test the new version with
69+
total confidence:
70+
71+
.. code-block:: bash
72+
73+
$ cd projects/my_project/
74+
$ git checkout -b testing_new_symfony
75+
# ... update composer.json configuration
76+
$ composer update symfony/symfony
77+
78+
# ... after testing the new Symfony version
79+
$ git checkout master
80+
$ git branch -D testing_new_symfony

‎cookbook/install/upgrading.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
How to Upgrade Your Symfony Project
2+
===================================
3+
4+
So a new Symfony release has come out and you want to upgrade, great! Fortunately,
5+
because Symfony protects backwards-compatibility very closely, this *should*
6+
be quite easy.
7+
8+
There are two types of upgrades, and both are a little different:
9+
10+
* :ref:`upgrading-patch-version`
11+
* :ref:`upgrading-minor-version`
12+
13+
.. _upgrading-patch-version:
14+
15+
Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
16+
-----------------------------------------------
17+
18+
If you're upgrading and only the patch version (the last number) is changing,
19+
then it's *really* easy:
20+
21+
.. code-block:: bash
22+
23+
$ composer update symfony/symfony
24+
25+
That's it! You should not encounter any backwards-compatibility breaks or
26+
need to change anything else in your code. That's because when you started
27+
your project, your ``composer.json`` included Symfony using a constraint
28+
like ``2.6.*``, where only the *last* version number will change when you
29+
update.
30+
31+
You may also want to upgrade the rest of your libraries. If you've done a
32+
good job with your `version constraints`_ in ``composer.json``, you can do
33+
this safely by running:
34+
35+
.. code-block:: bash
36+
37+
$ composer update
38+
39+
But beware. If you have some bad `version constraints`_ in your ``composer.json``,
40+
(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
41+
to new versions that contain backwards-compatibility breaking changes.
42+
43+
.. _upgrading-minor-version:
44+
45+
Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
46+
-----------------------------------------------
47+
48+
If you're upgrading a minor version (where the middle number changes), then
49+
you should also *not* encounter significant backwards compatibility changes.
50+
For details, see our :doc:`/contributing/code/bc`.
51+
52+
However, some backwards-compatibility breaks *are* possible, and you'll learn
53+
in a second how to prepare for them.
54+
55+
There are two steps to upgrading:
56+
57+
:ref:`upgrade-minor-symfony-composer`;
58+
:ref:`upgrade-minor-symfony-code`
59+
60+
1) Update the Symfony Library via Composer
61+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62+
63+
First, you need to update Symfony by modifying your ``composer.json`` file
64+
to use the new version:
65+
66+
.. code-block:: json
67+
68+
{
69+
"...": "...",
70+
71+
"require": {
72+
"php": ">=5.3.3",
73+
"symfony/symfony": "2.6.*",
74+
"...": "... no changes to anything else..."
75+
},
76+
"...": "...",
77+
}
78+
79+
Next, use Composer to download new versions of the libraries:
80+
81+
.. code-block:: bash
82+
83+
$ composer update symfony/symfony
84+
85+
You may also want to upgrade the rest of your libraries. If you've done a
86+
good job with your `version constraints`_ in ``composer.json``, you can do
87+
this safely by running:
88+
89+
.. code-block:: bash
90+
91+
$ composer update
92+
93+
But beware. If you have some bad `version constraints`_ in your ``composer.json``,
94+
(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
95+
to new versions that contain backwards-compatibility breaking changes.
96+
97+
2) Updating Your Code to Work with the new Version
98+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
In theory, you should be done! However, you *may* need to make a few changes
101+
to your code to get everything working. Additionally, some features you're
102+
using might still work, but might now be deprecated. That's actually ok,
103+
but if you know about these deprecations, you can start to fix them over
104+
time.
105+
106+
Every version of Symfony comes with an UPGRADE file that describes these
107+
changes. Below are links to the file for each version, which you'll need
108+
to read to see if you need any code changes.
109+
110+
.. tip::
111+
112+
Don't see the version here that you're upgrading to? Just find the
113+
UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_.
114+
115+
Upgrading to Symfony 2.6
116+
........................
117+
118+
First, of course, update your ``composer.json`` file with the ``2.6`` version
119+
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
120+
121+
Next, check the `UPGRADE-2.6`_ document for details about any code changes
122+
that you might need to make in your project.
123+
124+
Upgrading to Symfony 2.5
125+
........................
126+
127+
First, of course, update your ``composer.json`` file with the ``2.5`` version
128+
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
129+
130+
Next, check the `UPGRADE-2.5`_ document for details about any code changes
131+
that you might need to make in your project.
132+
133+
.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md
134+
.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md
135+
.. _`Symfony Repository`: https://github.com/symfony/symfony
136+
.. _`Composer Package Versions`: https://getcomposer.org/doc/01-basic-usage.md#package-versions
137+
.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions

‎cookbook/map.rst.inc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,11 @@
114114

115115
* :doc:`/cookbook/frontend/bower`
116116

117+
* :doc:`/cookbook/install/index`
118+
119+
* :doc:`/cookbook/install/upgrading`
120+
* :doc:`/cookbook/install/unstable_versions`
121+
117122
* :doc:`/cookbook/logging/index`
118123

119124
* :doc:`/cookbook/logging/monolog`

‎redirection_map‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
/cookbook/service_container/parentservices /components/dependency_injection/parentservices
1515
/cookbook/service_container/factories /components/dependency_injection/factories
1616
/cookbook/service_container/tags /components/dependency_injection/tags
17+
/cookbook/upgrading /cookbook/install/upgrading
1718
/reference/configuration/mongodb /bundles/DoctrineMongoDBBundle/config
1819
/reference/YAML /components/yaml
1920
/components/dependency_injection /components/dependency_injection/introduction

0 commit comments

Comments
 (0)