[wp-hackers] WordPress Version Numbers for BackPress

[Jacob Santos]

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[1] of when it is added." 
More to the point, the @since tags aren't important enough to really 
think too much [9].

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[2]. The only exception to 
this was Kses[3].

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[4].

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[5]. I think phpDocumentor might have some limitations to only one 
@since tag, but I'm unsure of whether is the case[6]. 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 
WordPress [7].

Jacob Santos

[1] 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.

[2] 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.

[3] 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 
WordPress.

[4] 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.

[5] 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.

[6] Even if phpDocumentor only accepts one, having the information in 
the inline documentation and available for your project Charles should 
suffice for the future.

[7] 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 [8].

[8] Those friends would have to be worthless as humans and I hope you 
walk over them wherever you go.

[9] 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 
running on.

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
>>> number.)
>>>
>>> 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 
>>> version
>>> 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.
>
> westi