[WCM] Revamped the Quick Start tutorial #4374

javiereguiluz · 2014-10-25T17:22:45Z

Q	A
Doc fix?	yes
New docs?	yes
Applies to	master (2.6+)
Fixed tickets	#4360

This is a total revamp of the Quick Start tutorial. Following the recent trend in the Symfony world, everything is simpler now. The main changes are:

The tutorial requires PHP 5.4 because this way everything is simpler. By the way, PHP 5.3 is unsupported since August 2014 and it's extremely dangerous to keep using it.
We use the AppBundle and the other changes that will introduce the standard edition soon. There are some pending PR.
Some advanced features, such as HTTP caching, have been removed. This tutorial is aimed for the total newcomer and it doesn't make sense to confuse him/her with things not needed at first.

There is one important thing missing:

The section about installing Symfony is pending of the new Symfony installer, specially for Windows users.

And one last comment:

Someone, which I cannot remember, commented a few weeks ago that maybe we should get rid of the different versions of this tutorial. I agree that the tutorial aimed for newcomers should be unique to avoid confusions and it should always explain the latest and greatest Symfony features. I've created this PR against the master branch for that reason and I ask the doc managers (@weaverryan, @wouterj and @xabbuh) to think about removing all the previous versions of this tutorial.

wouterj · 2014-10-25T17:33:19Z

The tutorial requires PHP 5.4 because this way everything is simpler. By the way, PHP 5.3 is unsupported since August 2014 and it's extremely dangerous to keep using it.

What does require PHP 5.4?

Btw, I'll review the PR another time :)

javiereguiluz · 2014-10-25T17:36:35Z

@wouterj PHP 5.4 is needed for the new Symfony Installer and for the built-in web server.

xabbuh · 2014-10-25T19:29:57Z

I've created this PR against the master branch for that reason and I ask the doc managers (@weaverryan, @wouterj and @xabbuh) to think about removing all the previous versions of this tutorial.

👍 (since I already if we actually need different versions of it :))

xabbuh · 2014-10-25T19:31:58Z

@javiereguiluz Actually, I don't think that we can technically get rid of different versions of the quick tour (given how Git works). But links can be changed on symfony.com to only link to one version, right?

xabbuh · 2014-10-25T19:32:27Z

quick_tour/the_architecture.rst

@@ -13,17 +13,17 @@ Understanding the Directory Structure
 The directory structure of a Symfony :term:`application` is rather flexible,
 but the recommended structure is as follows:

-* ``app/``:    the application configuration;
-* ``src/``:    the project's PHP code;
+* ``app/``: the application configuration and templates;


translations too

+1. There are also probably some other things, but I think 3 is enough - it gives you the right idea.

Yes, but these three are important in my opinion as they are all explained in the Best Practices book.

wouterj · 2014-10-25T19:42:43Z

Actually, I don't think that we can technically get rid of different versions of the quick tour (given how Git works).

We can, we just have to remove the quick tour each time we create a new version branch

xabbuh · 2014-10-25T19:47:14Z

Hm, yes, you're right. We could keep it only in master.

xabbuh · 2014-11-01T10:14:12Z

quick_tour/the_architecture.rst

@@ -73,12 +74,21 @@ A bundle is kind of like a plugin in other software. So why is it called a
 Symfony, from the core framework features to the code you write for your
 application.

+All the code you write for your application is organized in bundles. In Symfony
+speak, a bundle is a structured set of files (PHP files, stylesheets, JavaScripts,
+images, ...) that implements a single feature (a blog, a forum, ...) and which


implement (it refers to files, doesn't it?)

This is the same phrase use originally in the tutorial. I think it's correct because "implements" refers to the bundle, not the files. But maybe the wording is confusing and we could change it. What do you think?

I think it's fine so.

xabbuh · 2014-11-01T10:40:12Z

quick_tour/the_controller.rst

@@ -98,34 +218,73 @@ Errors will inevitably happen during the execution of every web application.
 In the case of ``404`` errors, Symfony includes a handy shortcut that you can
 use in your controllers::

-    throw $this->createNotFoundException();
+    // src/AppBundle/Controller/DefaultController.php


You should add the // ... placeholder.

xabbuh · 2014-11-04T10:29:09Z

quick_tour/the_view.rst

-under your web root directory without changing anything in your template's
-code.
+The ``asset()`` function looks for the web assets inside the ``web/`` directory.
+If you store them in another directory, read :doc:`this article <cookbook/assetic/asset_management>`


starting slash is missing

weaverryan · 2014-11-05T15:47:45Z

@javiereguiluz Thanks for taking this big step. Here's what I think we should do:

Check out the comments and make updates. There are some good ones :).
I'll then merge in and re-read everything from end-to-end and create a separate PR with tweaks (since the changes are big, it's better to re-read the whole thing).

Thanks!

javiereguiluz · 2014-11-12T17:04:33Z

@weaverryan I've addressed almost all of the suggestions made by reviewers, so I think we're good for the first merge. Then, let's create a separate PR to fix anything else. Thanks!

weaverryan · 2014-11-13T15:19:19Z

Hey guys! I've merged this in, but into the 2.3 branch for now. I like the idea of only having one version of this, but it seems that would require some changes to the site. If we delete this from the 2.3 branch, for example, then this would 404 on the 2.3 page, correct? Anyways, I'm happy to figure this out, but I don't want that to hold us up. If I'm missing something, let me know! Thanks!

@weaverryan

This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #4374). Discussion ---------- [WCM] Revamped the Quick Start tutorial | Q | A | ------------- | --- | Doc fix? | yes | New docs? | yes | Applies to | master (2.6+) | Fixed tickets | #4360 This is a total revamp of the Quick Start tutorial. Following the recent trend in the Symfony world, everything is simpler now. The main changes are: * The tutorial requires PHP 5.4 because this way everything is simpler. By the way, PHP 5.3 is unsupported since August 2014 and it's extremely dangerous to keep using it. * We use the `AppBundle` and the other changes that will introduce the standard edition soon. There are some pending PR. * Some advanced features, such as HTTP caching, have been removed. This tutorial is aimed for the total newcomer and it doesn't make sense to confuse him/her with things not needed at first. There is one important thing missing: * The section about installing Symfony is pending of the new Symfony installer, specially for Windows users. And one last comment: * Someone, which I cannot remember, commented a few weeks ago that maybe we should get rid of the different versions of this tutorial. I agree that the tutorial aimed for newcomers should be unique to avoid confusions and it should always explain the latest and greatest Symfony features. I've created this PR against the master branch for that reason and I ask the doc managers (@weaverryan, @wouterj and @xabbuh) to think about removing all the previous versions of this tutorial. Commits ------- 811f6e8 Included a bunch of fixes suggested by the awesome Symfony doc reviewers 940924c Added a bunch of fixes suggested by @xabbuh 6105acb Fixed a RST formatting issue baf4b9b Revamped the Quick Start tutorial

Revamped the Quick Start tutorial

531fc24

Fixed a RST formatting issue

4725c16

xabbuh reviewed Oct 25, 2014
View reviewed changes

wouterj added the Status: Needs Work label Oct 26, 2014

xabbuh reviewed Nov 1, 2014
View reviewed changes

Added a bunch of fixes suggested by @xabbuh

fe20efd

xabbuh reviewed Nov 4, 2014
View reviewed changes

wouterj mentioned this pull request Nov 7, 2014

Update book to comply with best practices #4431

Closed

13 tasks

Included a bunch of fixes suggested by the awesome Symfony doc reviewers

1ca388e

weaverryan closed this Nov 13, 2014

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WCM] Revamped the Quick Start tutorial #4374

[WCM] Revamped the Quick Start tutorial #4374

javiereguiluz commented Oct 25, 2014

wouterj commented Oct 25, 2014

javiereguiluz commented Oct 25, 2014

xabbuh commented Oct 25, 2014

xabbuh commented Oct 25, 2014

xabbuh Oct 25, 2014

weaverryan Nov 5, 2014

xabbuh Nov 5, 2014

wouterj commented Oct 25, 2014

xabbuh commented Oct 25, 2014

xabbuh Nov 1, 2014

javiereguiluz Nov 1, 2014

wouterj Nov 4, 2014

xabbuh Nov 1, 2014

xabbuh Nov 4, 2014

weaverryan commented Nov 5, 2014

javiereguiluz commented Nov 12, 2014

weaverryan commented Nov 13, 2014

[WCM] Revamped the Quick Start tutorial #4374

[WCM] Revamped the Quick Start tutorial #4374

Conversation

javiereguiluz commented Oct 25, 2014

wouterj commented Oct 25, 2014

javiereguiluz commented Oct 25, 2014

xabbuh commented Oct 25, 2014

xabbuh commented Oct 25, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wouterj commented Oct 25, 2014

xabbuh commented Oct 25, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

weaverryan commented Nov 5, 2014

javiereguiluz commented Nov 12, 2014

weaverryan commented Nov 13, 2014