Update 'How to Create and store a Symfony2 Project in Git' #3827

nicwortel · 2014-05-03T17:32:49Z

This pull request updates the cookbook article How to Create and store a Symfony2 Project in Git.

It started with this question (and its answer by Wouter J) on Stack Overflow.

Q	A
Doc fix?	yes
New docs?	no
Applies to	all (or 2.3+)
Fixed tickets	n/a

As confirmed by WouterJ on Stack Overflow [1], the example .gitignore file [2] is not up-to-date. This commit updates the documentation to reflect the current state of the .gitignore file that is included in the Symfony Standard Edition distribution [3]. [1] http://stackoverflow.com/q/23437768/1001110 [2] http://symfony.com/doc/current/cookbook/workflow/new_project_git.html#initial-project-setup [3] https://github.com/symfony/symfony-standard/blob/master/.gitignore

wouterj · 2014-05-03T17:58:12Z

👍

cordoval · 2014-05-03T18:07:17Z

cookbook/workflow/new_project_git.rst

@@ -32,11 +32,16 @@ git repository:
   .. code-block:: text

        /web/bundles/
-        /app/bootstrap*


if this is the case add the SymfonyRequirements class as sometimes is good to remove it or ignore it, same with config and check scripts 👶

I don't see why you put that comment on this line. Besides that, I'm missing what you want to say. The files listed here are things that generally should be ignored, ignoring config/check scripts is something that doesn't belong in that list imo

it is more for more slim approaches, these files change anyway depending on the OS are are files that can be cleaned up

This PR only changes the documentation to reflect the actual .gitignore. If you'd want to propose a change to the file, you should probably do it in the Symfony Standard Edition repository, not here.

wouterj · 2014-05-04T12:37:37Z

I've read some context now and I think the steps need a small rewrite. Can you do this in this PR please? (otherwise, I'll create a new one myself)

The first 2 steps talk about downloading and unzippen the Standard Edition. This is not the recommend way, it should be changed to use composer create-project. With this, step 7 can be removed;
The description of step 3 (the one you edited) is not accurate. There is already a .gitignore file with the correct things in the Standard Edition. Instead, it should say something among the lines of "If it is not yet done, a .gitignore file should be added to the root of your project (e.g. next to the composer.json file), take a look at the .gitignore file of the Standard Edition for an example;" The .gitignore file example should be removed from this step, to avoid having outdated docs on this topic again.

As proposed by WouterJ in #3827 this commit rewrites the 'Initial Project Setup' paragraph. The documentation now describes the recommended way of creating a new Symfony2 project, using Composer to download the Standard Distribution + vendors (instead of downloading the zipped version). As the Standard Edition already contains a .gitignore, the example is replaced by a link to the one stored at GitHub. The article also explains which files are excluded by .gitignore. The last step (downloading vendor libraries using Composer) is removed as this is now covered by step 1.

nicwortel · 2014-05-05T09:10:31Z

@wouterj done! What do you think?

wouterj · 2014-05-05T09:24:20Z

cookbook/workflow/new_project_git.rst

+   You'll also want to keep your ``parameters.yml`` out of your repository as it will
+   contain sensitive information, such as database credentials. Furthermore,
+   files that are automatically created by Symfony (such as logs, caches, and dumped
+   assets) should be excluded as well.


I think we should make this bit a bit shorter, besides that the sentence about "parameters.yml" is wrong, you want to ignore this because this file is created from the parameters.yml.dist file.

I propose something like: "Your project folder will now contain all files of the Standard Edition, as well as all the third party code, automatically created files (e.g. logs, caches, dumped assets) and environment specific information (e.g. the parameters.yml file). You don't want to have this files included in your Git repository."

the reason to ignore parameters.yml is right. The reason why we ignore it and provide a dist file for it is indeed because it contains sensitive info (your DB password)

@wouterj that's correct, however, AFAIK the reason that parameters.yml.dist exists in the first place is because of the sensitive information in parameters.yml that you don't want to store in git. (and also because it contains some other settings that should differ between installations of the application)

I agree that step 2 is getting a little long (in fact, it's not even a step, but merely side information). Perhaps it should be a tip (or another kind of side-content), too? Or should it be moved to another location? What do you think?

I like the explanation of parameters.yml now, and in general, I like this explanation. I don't think we cover the specific reasons for ignoring these different files anywhere else in the docs.

wouterj · 2014-05-05T09:25:30Z

Except from some minor things, it looks great 👍

...so we don't have to renumber them every time we remove/add a new item.

weaverryan · 2014-05-09T17:50:08Z

cookbook/workflow/new_project_git.rst

-3. Create a new file called ``.gitignore`` at the root of your new project
-   (e.g. next to the ``composer.json`` file) and paste the following into it. Files
-   matching these patterns will be ignored by Git:
+        $ php composer.phar create-project symfony/framework-standard-edition path/ 2.4.4


What do you guys think about using "~2 here instead of 2.4.4? I actually wish symfony.com/download did that too.

~2 means * so -1 for that However, I'm +1 for using 2.* or ~2.3

symfony.com/download is automatically updated to the latest stable version, because they want to show the latest stable version number on the download page.

no. ~2 is equivalent to ~2.0 or 2.*. The semantic versionning operator never allows changing major version as this implies BC break.

I would use ~2.3 or ~2.4 in the doc. It makes sense to allow future versions, but it does not make sense to allow 2.0 while your code won't run with it

I agree that using the next significant release constraint makes more sense than a fixed version number. However, ~2 being equivalent to ~2.0 is not what I understand from the documentation at Composer.org:

Another way of looking at it is that using ~ specifies a minimum version, but allows the last digit specified to go up.

This implies to me that ~2 would also allow 3.x, 4.x, etc. which is obviously not desirable. Perhaps @weaverryan and @stof are right, in which case the documentation of Composer is incorrect / outdated.

If ~2 is indeed equivalent to ~2.0, would that be a correct version constraint? Or should I just use ~2.3 or ~2.4? In that case this should be updated every time a new minor version is released...

@nicwortel I'm talking about the way ~2 works, not about the way it is documented. The documentation of Composer should be improved on this point.

It would not make sense to allow bumping the major version for a next significant release operator. It would make it the same than >=2, allowing anything in the future with all BC breaks included. This is the opposite of the goal of the ~ operator.

@stable is the same than *@stable, and the same than * by default (as the default minimum stability is stable). It is an unbound constraint. If you use @stable or * as requirement, your project will start using Symfony 3.0 as soon as it is released and break (because bumping to 3.0 will mean that we are not BC)

btw, try using it and validating your composer.json (with an uptodate composer). you will get a warning about being unbound (SensioLabs Insight also warns about it)

Hmm, then my vote is still for ~2. This is for a new project, so I'm not convinced that the fact that this technically includes 2.0 as a problem. I think it's the best user-experience.

I also what @javiereguiluz is planning on showing people on the new symfony.com download page he's working on.

I don't. If you have a bundle doing a crap in its version constraint and the only installable version is the old version compatible with 2.0, this would automatically revert your project back to Symfony 2.0 because composer will think it is compatible, while your code is probably not.
And given the number of Symfony releases since 2.0 and the number of subpackages in it, reducing the range of versions matched at the root level makes a huge difference when running composer (both in term of speed and memory usage).
If you don't want to change it in each branch, at least use ~2.3

~2.3 it is, then! However, perhaps later on we'll have to re-evaluate if ~2.3 still makes sense.

...as suggested by weaverryan.

...with a smarter one. Using Composer's tilde operator (~), also known as the next significant release constraint, we instruct composer to use at least Symfony 2.3, but not 3.0 or higher.

Shorten the 2nd list item a bit, and move it into a 'Tip' seems to make more sense.

weaverryan · 2014-05-16T12:56:51Z

cookbook/workflow/new_project_git.rst

+      As you might have noticed, not all files that were downloaded by Composer in step 1,
+      have been staged for commit by Git. Certain files and folders, such as the project's
+      dependencies (which are managed by Composer), ``parameters.yml`` (which contains sensitive
+      information such as database credentials), log- and cache files and dumped assets (which are


extra - here on log-

nicwortel · 2014-05-21T09:56:07Z

This PR can be merged, as far as I'm concerned!

weaverryan · 2014-05-27T18:59:22Z

I agree - it's much much improved! Thanks for your hard work on this Nic!

…(nicwortel) This PR was merged into the 2.3 branch. Discussion ---------- Update 'How to Create and store a Symfony2 Project in Git' This pull request updates the cookbook article [How to Create and store a Symfony2 Project in Git](http://symfony.com/doc/current/cookbook/workflow/new_project_git.html#initial-project-setup). It started with [this question (and its answer by Wouter J) on Stack Overflow](http://stackoverflow.com/q/23437768/1001110). | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | all (or 2.3+) | Fixed tickets | n/a Commits ------- 3f3d886 Update the tip about the global .gitignore 1baf7e0 Remove dash 6fd5e52 Small improvement d9f72f9 Some refactoring of the article 083c1f5 Replace static version constraint (2.4.4) 32cee81 Small change in the wording 311f14b Replace numbered list items with # 6a19628 Indent the tip to be on the same level as the list item 34d61eb Update the complete 'Initial Project Setup' paragraph 011e0f0 Update .gitignore example

cordoval reviewed May 3, 2014
View reviewed changes

nicwortel changed the title ~~Update .gitignore example~~ [WIP] Update .gitignore example May 4, 2014

nicwortel changed the title ~~[WIP] Update .gitignore example~~ [WIP] Update 'How to Create and store a Symfony2 Project in Git' May 5, 2014

wouterj reviewed May 5, 2014
View reviewed changes

nicwortel added 2 commits May 5, 2014 20:22

Indent the tip to be on the same level as the list item

6a19628

Replace numbered list items with #

311f14b

...so we don't have to renumber them every time we remove/add a new item.

weaverryan reviewed May 9, 2014
View reviewed changes

Nic Wortel added 4 commits May 13, 2014 14:08

Small change in the wording

32cee81

...as suggested by weaverryan.

Replace static version constraint (2.4.4)

083c1f5

...with a smarter one. Using Composer's tilde operator (~), also known as the next significant release constraint, we instruct composer to use at least Symfony 2.3, but not 3.0 or higher.

Some refactoring of the article

d9f72f9

Shorten the 2nd list item a bit, and move it into a 'Tip' seems to make more sense.

Small improvement

6fd5e52

weaverryan reviewed May 16, 2014
View reviewed changes

Nic Wortel added 2 commits May 19, 2014 10:51

Remove dash

1baf7e0

Update the tip about the global .gitignore

3f3d886

nicwortel changed the title ~~[WIP] Update 'How to Create and store a Symfony2 Project in Git'~~ Update 'How to Create and store a Symfony2 Project in Git' May 21, 2014

nicwortel mentioned this pull request May 22, 2014

Create a canonical article about Composer #3860

Closed

weaverryan merged commit 3f3d886 into symfony:2.3 May 27, 2014

nicwortel deleted the update_gitignore_documentation branch June 26, 2014 15:03

Uh oh!

Update 'How to Create and store a Symfony2 Project in Git' #3827

Update 'How to Create and store a Symfony2 Project in Git' #3827

Uh oh!

Conversation

nicwortel commented May 3, 2014

Uh oh!

wouterj commented May 3, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterj commented May 4, 2014

Uh oh!

nicwortel commented May 5, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterj commented May 5, 2014

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicwortel commented May 21, 2014

Uh oh!

weaverryan commented May 27, 2014

Uh oh!

Uh oh!