[wp-hackers] WordPress Version Numbers for BackPress
wordpress at santosj.name
Wed Mar 25 01:38:07 GMT 2009
I think the difficulty I had was that I don't see BackPress as part of
WordPress. The question, to me, is not that, "This is part of WordPress
and should have a WordPress @since info," but more, "This is BackPress
and therefore has a BackPress revision number of when it is added."
More to the point, the @since tags aren't important enough to really
think too much .
The problem with saying, "@since 2.7.0 (BackPress version: r79)" is that
it becomes ambiguous. Which 2.7.0 are you referencing? bbPress will
eventually have a 2.7.0 and to those users of bbPress using that
function, will think that the 2.7.0 refers to bbPress as opposed to
WordPress. It is problematic, indeed, but unless phpDocumentor allows
for multiple @since tags (I have not yet tested this, because there
wasn't much of a need for it).
Again, I see BackPress as a separate library, and like Peter Westwood
mentioned, BackPress may eventually be literally a separate library as
in it will be an external and added to the downloads and SVN checkouts.
In this case, WordPress version numbers would not make any sense. You do
not add @since to other external libraries. The only exception to
this was Kses.
I believe the confusion was that some functions inside of BackPress
originated in WordPress and therefore should have a WordPress @since, as
WordPress is the "owner" of that function. I think this is confusing and
a practice I hope does not continue when bbPress is documented.
That being said, this only works if BackPress is continued to be
documented. This I think is further complicated that when WordPress
inline documentation is ported to BackPress, it will also keep the
@since information of WordPress. This will not be the case for bbPress.
I'm unsure of the best solution for this that would be quick and
simple. I think phpDocumentor might have some limitations to only one
@since tag, but I'm unsure of whether is the case. I forget if I
tried it, but if I did, then it most not have worked or I would have
used multiple @since when I came across backported functions.
Well, I guess the quick and simple is to keep the WP or use "@since
WordPress 2.7.0 (BackPress: r72)" but I fear that the solution will
become convoluted as bbPress version is added and future -Presses. I
would rather explore whether you can have multiple @since phpDoc tags
and have one for WordPress, BackPress, and bbPress. The other solution
would be to just have notes in the Codex as to when the BackPress
function was added to WordPress, or a little history tidbit about how
the WordPress function was ported to BackPress and then used in
 BackPress does not have any version number, because there has no
been any public release of it. This really just means that it is alpha
software. Really, all the @since info that has r### will have to be
updated when there is a release to whatever version that release is
labeled as. The only point of it from my perspective is that there has
to be some reference point for those using the library as a
svn:external. That said, those who are using the library, will always be
using the latest version and therefore will always have every function
and class. Thus the reversion numbers and @since is irrelevant. It is
only when there is a release to work off of that the @since info will
take hold for BackPress. Even then, all of the @since info will need to
be updated to reflect that version release.
 That would be wrong by the way to do, because it is entirely
unlikely the core devs of the external projects will accept something of
a patch exclusive to and for WordPress.
 Which I believe was dead before it was picked up and modified so
much in WordPress, that I felt the current implementation to be an
acceptable fork of the library and therefore needed documentation in
 Documenting WordPress was mostly an experimental project and there
are inconsistencies as better ways of expressing information was
explored and then found to not work as well in future additions.
 I want to point out that this is mostly a bikeshed argument in that
there isn't a "right" answer or solution. There are many working
solutions and by no means is the current one the "correct" or "best"
one. By all accounts, that does not appear to be the case, since it
assumes isolation and WordPress isn't isolated in this instance. This is
more of BackPress problem and more of one that is not important compared
to the @param, short and long descriptions. If it was known that it
would have been such a pain in the ass to maintain later, I wouldn't
have spent such a long time worrying about it and adding it.
What I'm trying to say, is that whatever you feel is the way to go, then
I will stand behind it and help in any way I can.
 Even if phpDocumentor only accepts one, having the information in
the inline documentation and available for your project Charles should
suffice for the future.
 I'd like to think that two years from now, people will be looking
back at this effort and get as much useful information as possible.
Perhaps also the information will be part of some quiz or useless
information used to impress friends .
 Those friends would have to be worthless as humans and I hope you
walk over them wherever you go.
 The @since tags are only important to those who care about the
minute details and want to maintain backwards compatibility. That said,
they will most likely be wrapping the function in "function_exists( ...
)" and not worrying about the exact version the plugin or theme is
Peter Westwood wrote:
> On 24 Mar 2009, at 13:50, Matt Martz wrote:
>> On Tue, Mar 24, 2009 at 9:39 AM, Charles K. Clarkson
>> <cclarkson at htcomp.net> wrote:
>>> Hello All,
>>> When was BackPress first added to WordPress? (Which WordPress version
>>> I ask because the "Since" version information in the BackPress source
>>> files uses BackPress version numbers. I have been including a Since
>>> section on the Function Reference pages and I fear the BackPress
>>> numbers would only serve to confuse most users.
>> It looks like the functions included in those files were added back as
>> far as 2.1. However those files were added in 2.6. Previously the
>> functions were in wp-includes/script-loader.php
> BackPress is more of a two way thing.
> It has grown out of the fact that bbPress started by taking some of
> the core WordPress code and it is an attempt at pulling out the stuff
> that is sharable between projects.
> Maybe one day WordPress will use BackPress as an svn:external in the
> same way bbPress does.
More information about the wp-hackers