Skip to content

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

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 10 commits into from
May 27, 2014
Merged

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

Changes from 4 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
011e0f0
Update .gitignore example
nicwortel May 3, 2014
34d61eb
Update the complete 'Initial Project Setup' paragraph
nicwortel May 4, 2014
6a19628
Indent the tip to be on the same level as the list item
nicwortel May 5, 2014
311f14b
Replace numbered list items with #
nicwortel May 5, 2014
32cee81
Small change in the wording
May 13, 2014
083c1f5
Replace static version constraint (2.4.4)
May 16, 2014
d9f72f9
Some refactoring of the article
May 16, 2014
6fd5e52
Small improvement
May 16, 2014
1baf7e0
Remove dash
May 19, 2014
3f3d886
Update the tip about the global .gitignore
May 19, 2014
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
52 changes: 29 additions & 23 deletions cookbook/workflow/new_project_git.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,51 +20,55 @@ Initial Project Setup
To get started, you'll need to download Symfony and initialize your local
git repository:

1. Download the `Symfony2 Standard Edition`_ without vendors.
#. Download the `Symfony2 Standard Edition`_ using Composer:
Copy link
Member

Choose a reason for hiding this comment

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

Let's add a sentence after this:

First, download Composer_: this will give you a composer.phar file.
Now, run the next command from anywhere on your system: it downloads a starting
Symfony project into a path/ directory (you can change this in the command):

I realize we have detailed installation details in multiple places, at some point we should consolidate. I just want to be very complete so a user can step through things.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Perhaps there should be one canonical article about using Composer? All other articles could reference to that article for more information about installing and using Composer.

Copy link
Member

Choose a reason for hiding this comment

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

Yea, I think there should be :).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think we should leave it as it is right now. The article links to Installing Symfony using Composer where more information about using Composer can be found. It might be a good idea to create a dedicated article about Composer, but that should probably be another pull request.


2. Unzip/untar the distribution. It will create a folder called Symfony with
your new project structure, config files, etc. Rename it to whatever you like.
.. code-block:: bash

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
Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

~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.

Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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...

Copy link
Member

Choose a reason for hiding this comment

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

@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.

Copy link
Member

Choose a reason for hiding this comment

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

@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)

Copy link
Member

Choose a reason for hiding this comment

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

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)

Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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


.. code-block:: text
Composer will now download the Standard Distribution along with all of the
required vendor libraries. For more information about downloading Symfony using
Composer, see `Installing Symfony using Composer`_.

/web/bundles/
/app/bootstrap*
/app/cache/*
/app/logs/*
/vendor/
/app/config/parameters.yml
#. Your project folder will now contain files of the Symfony framework, as well
Copy link
Member

Choose a reason for hiding this comment

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

What do you think about this:

... files for your new project, as well

To me, the "Symfony framework" is a vendor library. I think we're trying to say "you have project files and vendor files", and if so, this is clearer. Let me know if you agree :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

You are right, I've changed the wording as you suggested. Thanks!

as files and folders for vendor libraries. You'll want to store your project
files in Git, but not the dependencies, since they will be managed by Composer.
Copy link
Contributor

Choose a reason for hiding this comment

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

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 👶

Copy link
Member

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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.

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.
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 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."

Copy link
Member

Choose a reason for hiding this comment

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

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)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@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?

Copy link
Member

Choose a reason for hiding this comment

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

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.


.. tip::
To help you keep these files out of your repository, Symfony comes with a file
called ``.gitignore``. It contains a list of files and folders that Git will
ignore.

The contents of the ``.gitignore`` file that comes with the Standard Distribution
can be found in the `GitHub repository`_.

You may also want to create a .gitignore file that can be used system-wide,
in which case, you can find more information here: `Github .gitignore`_
This way you can exclude files/folders often used by your IDE for all of your projects.
.. tip::

4. Initialize your Git repository:
You may also want to create a .gitignore file that can be used system-wide,
in which case, you can find more information here: `Github .gitignore`_
This way you can exclude files/folders often used by your IDE for all of your projects.

#. Initialize your Git repository:

.. code-block:: bash

$ git init

5. Add all of the initial files to Git:
#. Add all of the initial files to Git:

.. code-block:: bash

$ git add .

6. Create an initial commit with your started project:
#. Create an initial commit with your started project:

.. code-block:: bash

$ git commit -m "Initial commit"

7. Finally, download all of the third-party vendor libraries by
executing Composer. For details, see :ref:`installation-updating-vendors`.

At this point, you have a fully-functional Symfony2 project that's correctly
committed to Git. You can immediately begin development, committing the new
changes to your Git repository.
Expand Down Expand Up @@ -111,6 +115,8 @@ manage this is `Gitolite`_.

.. _`Git`: http://git-scm.com/
.. _`Symfony2 Standard Edition`: http://symfony.com/download
.. _`Installing Symfony using Composer`: http://symfony.com/doc/current/book/installation.html#option-1-composer
.. _`GitHub repository`: https://github.com/symfony/symfony-standard/blob/master/.gitignore
.. _`git submodules`: http://git-scm.com/book/en/Git-Tools-Submodules
.. _`GitHub`: https://github.com/
.. _`barebones repository`: http://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository
Expand Down