Le 07/01/2013 15:37, Victor Berchet a écrit :
Let me give more details on why I think the "versionadded" tag is bad:
- The doc will become more and more confusing as Symfony2 get more
releases: new in 2.1, new in 2.2, new in 2.3, ..., new in 2.8. The way
it is used today is also confusing: we sometimes give examples that
work with most releases but is no more the preferred way of doing
things, so you have to read the "generic" way and then patch it with
the "new in 2.x" comments.
- The usage of "versionadded" is not consistent: it is randomly used
and branch specific docs are used in the others cases - no guidelines
are given on when to use what,
- What will happen when something is introduce in 2.2 and modified in
2.4 ? you have to read the "generic" docs and apply to patches ?
That's why I think "versionadded" should be completely removed in
favor of branch specific content. But if you think otherwise, I would
be happy to hear your voice.
If we stick to the "versionadded" tag, we should give guidelines in
the contributing guide.
the versionadded tag has a benefit: a bundle author reading the latest
doc will be aware that this feature is new in the latest release,
meaning that using it in their bundle requires dropping the support of
older Symfony versions.
However, I agree that the examples should use the preferred way in the
release they document. We should find another way to indicate that it
has been modified since the previous release and so requires some work
to support both.
--
Christophe | Stof
--
--
If you want to report a vulnerability issue on Symfony, please read the
procedure on http://symfony.com/security
You received this message because you are subscribed to the Google
Groups "symfony developers" group.
To post to this group, send email to symfony-devs@googlegroups.com
To unsubscribe from this group, send email to
symfony-devs+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/symfony-devs?hl=en
