Link to FOSHttpCacheBundle #4175
Conversation
ddeboer
commented
Aug 24, 2014
- Link to FOSHttpCacheBundle that can help with cache invalidation.
- Qualify the strong negative opinion about cache invalidation, which we also find in the Cache Invalidation section in the docs. The cookbook (and docs) are too opiniated on this subject and offer no balanced view. We should not forget that RFC 2616 considers invalidation seriously. I would love to hear from the original authors of this doc section or any others what their arguments against invalidation are. Let’s try to introduce both benefits and drawbacks more carefully in the docs (e.g., as is done here).
| @@ -232,3 +240,5 @@ absolute URLs: | |||
| .. _`Edge Architecture`: http://www.w3.org/TR/edge-arch | |||
| .. _`GZIP and Varnish`: https://www.varnish-cache.org/docs/3.0/phk/gzip.html | |||
| .. _`Surrogate-Capability Header`: http://www.w3.org/TR/edge-arch | |||
| .. _`cache invalidation`: http://tools.ietf.org/html/rfc2616#section-13.10 | |||
| .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/ | |||
There was a problem hiding this comment.
When we link to a Symfony bundle, should we link to its official home page (https://github.com/FriendsOfSymfony/FOSHttpCacheBundle in this case) or to its official documentation (http://foshttpcachebundle.readthedocs.org/ in this case)?
I don't know if there is an official policy set by the documentation maintainers: @weaverryan @wouterj @xabbuh
There was a problem hiding this comment.
Afaik there is no strict guideline regarding this. But linking to the official documentation seems reasonable to me since this is what people are usually interested in when reading the documentation. We do this in the Serializer Component documentation for the JMS Serializer for example (the CMF is linking to https://github.com/schmittjoh/JMSSerializerBundle btw., @wouterj).
|
looks good to me. |
@javiereguiluz @xabbuh That for me was the reason to link to the docs as well. On the other hand, readers may want to have a look at the GitHub page too and see whether anyone else is using the bundle, whether it’s still being maintained etc. in order to assess whether it’s a good idea to start using it. Would linking to both docs and GitHub be overkill? @dbu Good idea, we should follow this more balanced line there, too. |
|
@ddeboer The FOSHttpCacheBundle documentation already links to the GitHub repository on the first page. So, I don't think that there is any need to add a link to GitHub too. |
|
Good point, so we can keep it this way. If you guys are okay with the text I added, please go ahead and merge this. If not, let me know so I can change things. |
|
Really great message imo and new link. The original cache invalidation messaging was probably written by me or Fabien, and was not meant to necessarily be overly strong. In other words, I'm very comfortable with what you have here. Also, linking to a high-quality bundle in the docs is always something we should be doing. So, this is great! |
This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #4175). Discussion ---------- Link to FOSHttpCacheBundle * Link to FOSHttpCacheBundle that can help with cache invalidation. * Qualify the strong negative opinion about cache invalidation, which we also find in the [Cache Invalidation section](http://symfony.com/doc/current/book/http_cache.html#http-cache-invalidation) in the docs. The cookbook (and docs) are too opiniated on this subject and offer no balanced view. We should not forget that [RFC 2616](http://tools.ietf.org/html/rfc2616#section-13.10) considers invalidation seriously. I would love to hear from the original authors of this doc section or any others what their arguments against invalidation are. Let’s try to introduce both benefits and drawbacks more carefully in the docs (e.g., as is done [here](http://foshttpcache.readthedocs.org/en/latest/invalidation-introduction.html)). Commits ------- 9243612 Link to FOSHttpCacheBundle