Add notes about assets' version

[jalliot]

At the moment, there is absolutely no information about these options in the doc:

• framework.templating.assets_version
• framework.templating.assets_version_format (which defaults to %s?%s in Symfony\Component\Templating\Asset\Package so that URLs look like my_asset.xyz?version)

Notes about those options should be added at least in these places:

• Book > Templates > Linking to assets
• Cookbook > How to use Assetic > Controlling the URL used
• And of course the FrameworkBundle configuration reference

These notes should explain what those options are for (basically versionning assets in a project for cache busting) and could link to something like this.

It should also be reminded (clear warning) to bump the assets version in the config file each time we deploy a new version of the assets in production.

[weaverryan]

Thanks for the very thorough description - this has indeed been missing for two long. We'll also need to document the related packages and base URL options. The reference section as a whole is probably next for me.

Thanks!

[jalliot]

This is great Ryan :)

Just one thing, the default %s?%s for framework.templating.assets_version_format is not set in the DIC but statically inside Symfony\Component\Templating\Asset\Package::__construct(). I'm not sure you should change the default null from the reference (or better we should change this default value to be set in the DIC extension).
What do you think?

[weaverryan]

I've debated this myself. I think what I have is technically wrong, but very practically right. I'm inclined to stick with showing them the "practical" default, until/unless someone can give me a really good argument on why not to.

Thanks!

[jalliot]

Fine by me ;)

@fabpot What do you think about moving the default value from the parameters of the constructor to the FrameworkBundle configuration extension? Something like that.