Skip to content

Added interlinking and fixed install template for reusable bundles #4377

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 2 commits into from
Nov 7, 2014
Merged

Added interlinking and fixed install template for reusable bundles #4377

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
94f04a4
Added interlinking between the 2 best practices
wouterj Oct 26, 2014
35d8e5f
Reverted removal of version
wouterj Oct 26, 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
10 changes: 9 additions & 1 deletion cookbook/bundles/best_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@ apply to application bundles because you'll want to keep those as simple
as possible. For application bundles, just follow the practices shown throughout
the book and cookbook.

.. seealso::

The best practices for application-specific bundles are discussed in
:doc:`/best_practices/introduction`.

Copy link
Member

Choose a reason for hiding this comment

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

like this - good link

Copy link
Member

Choose a reason for hiding this comment

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

We should just keep in mind not to merge this before the best practices chapter is rendered properly.

Copy link
Member

Choose a reason for hiding this comment

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

Do you just mean the bad styling on the "best practice" items? Or is there something else. I wouldn't let the first thing block us :)

Copy link
Member

Choose a reason for hiding this comment

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

There were some more style issues and I ink even some images weren't loaded. But this seems to be fixed: http://symfony.com/doc/current/best_practices/introduction.html

Copy link
Member

Choose a reason for hiding this comment

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

The issue is #4383.

.. index::
pair: Bundle; Naming conventions

Expand Down Expand Up @@ -219,7 +224,7 @@ following standardized instructions in your ``README.md`` file.
following command to download the latest stable version of this bundle:

```bash
$ composer require <package-name>
$ composer require <package-name> "~1"
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 like this. Why not let composer choose the best/latest version? As your not describes below, it sounds like this will just potentially create issues. Adding the version number is not something you see normally in other package managers (apt-get, npm, etc).

What's your thought behind this?

Copy link
Member Author

Choose a reason for hiding this comment

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

The installation chapter is the start of the documentation. You want to document against a specific version. When omitting the version, you'll be documenting 1.0 while 2.0 is installed (as an example)

Copy link
Member

Choose a reason for hiding this comment

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

Hmm, ok. Then we should have ~1.0, right? Wouldn't ~1 give you version 2 or 3 if it were out?

Copy link
Member Author

Choose a reason for hiding this comment

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

~1 is equal to ~1.0

Copy link
Member

Choose a reason for hiding this comment

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

Exactly. Here is what the Composer documentation has to say about it:

Note: The ~ operator has an exception on its behavior for the major release number. This means for example that ~1 is the same as ~1.0 as it will not allow the major number to increase trying to keep backwards compatibility.

Copy link
Member

Choose a reason for hiding this comment

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

Ah great, I didn't know about the exception for the major! It makes more sense that way anyways.

```

This command requires you to have Composer installed globally, as explained
Expand Down Expand Up @@ -254,6 +259,9 @@ following standardized instructions in your ``README.md`` file.
}
```

This template assumes that your bundle is in its ``1.x`` version. If not, change
the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)

Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
explain other required installation tasks, such as registering routes or
dumping assets.
Expand Down