Making a release

Put it online somwhere, send a link to the package as well as, if
possible, to phps-files to the pear-qa-list and we'll have a look.

Thank you very much for asking :-))
Stefan

Oh, alright ... missed that fact :-))

1) The examples should go into docs/examples/
Please have a look at the package directory structure:
http://pear.php.net/group/docs/20031114-pds.php

2) Since createDocument is static, please provide a @static-tag in
the phpdoc-comments. If peardoc-build then might fail for you, grab
an updated version of the peardoc-template from phpDocumentor ...
Greg recently corrected a problem with @static if I remember
correctly.

3) In createDocument: Maybe remove the unneeded spaces behind "$doc
=". One space before and one after the equal-sign is enough ...
though this is surely no real CS-issue ... just a suggestion. Similar
things at other places also. Maybe because you replaced tabs with 4
whitespaces.

4) Regarding XUL/Document.php:
imho "enableValidation()" with a parameter of false to disable
validation shounds a bit strange. But I haven't got a better name
atm. Maybe "setValidation()" to be consequent to your other API-
functions?

5) In XML_XUL_Element you let people access $replaceEntities directly
(public attribute) but e.g. for validation you encapsulate the
validation with an "enable" function-call? Is the replacing used less
often or why did you decide to let it be set by the user directly?

6) Since you have a method serialize(), would it be an idea to maybe
also have unserialize() for loading a stored XUL again? Don't know
about the background ... just generally had the idea ...

7) In validateAttributes() you don't need to do a
reset($this->attributes);
at the beginning. This is already done automatically by foreach,
refering to
http://de.php.net/foreach

8) In lastChild():
Imho you don't need the { } around $cnt-1, since the [] when
accessing the array already encapsulate.

9) Do you need all elements as separate objects / files? Since, as I
see it, $elementName always has the last part of the class name maybe
you could live fine with just a few classes? Or do you plan
additional implementations in all classes? If you plan additional
implementations, maybe it would be possible to avoid $elementName
since you can always digest it from the class name?

Didn't look at *all* specific elements - but all in all they seem
okay.


So from my side I didn't find any grave bugs ... just wrote down some
suggestions I head. All in all: Well done!

Stefan

Hi,
This is done automatically during packaging!
<file role="doc" baseinstalldir="XML"
md5sum="9be3f6bd9bafb815b011362a1c20436f"
name="examples/example_browser.php"/>
It's disabled by default, so you'll mostly call enableValidation()
without a parameter.
enableValidation() will in most cases only be used during testing, so
there's seldomly a need to disable it again...
replaceEntities is currently not needed and when it is needed it will be
needed it's only for a more profesional use... So there's no method for
this.
Not again :-)
I discussed this with Alan :-) There will be a method to read serialized
XUL documents, but it will be XUL::loadFile() and XUL::loadString().
I discussed this with Alan, too :-)
There will be additional methods for most of the elements. And I'll keep
the elementName property as it's more flexible. You could always come
up with any object that has some special features but creates the same
XUL tag... Furthermore it's faster that extraction the last part from
the classname...
I think most of this stuff could have been (and some already has been)
discussed during the proposal phase. I'm not quite sure what the tasks
of the QA team is in detail... But thanks nevertheless for checking the
code.

Stephan

On 5 Mar 2004 at 13:33, Stephan Schmidt wrote:

[...]
The main topic for PEAR QA are reacting to problems related to
quality. E.g. if a bug is very important or has been long standing
but the maintainer can't be reached, then PEAR QA should handle this.
Or if there are versioning-issues (like the 0.7-stable-release of a
package lately - which should have been 1.0 according to the rules)
we'll step in. However, since there has been recent discussion about
"maybe letting somebody look over the code before a release" this was
just a suggestion to clear those quite obvious errors before a
release. However, you haven't made any :-)) Well done!

So thank you for asking QA to have a look at the package. And don't
consider the points I mentioned really QA-related. It were just a few
minor points I came across during code-reading and that I wanted to
give you to maybe think over some points again. If you did everything
I mentioned intentional ("already discussed with Alan" etc.) that's
fine!
From my side I'd consider your package as very well done from the
quality-side. Don't get me wrong!


Thank you for your contributions. Keep up the good work
Stefan

Why not simply release an alpha as a first release?

No BC problems and allow QA to really test it as a normal package.
And not only QA can play with it.

pierre

Hi,
I'll release it as 0.6 beta.
There probably won't be any major API changes and BC is no problem in
version below 1.0

Stephan

Bad idea. Beta does not allow to solve APIs issues (if any) or any
other problem. I think it should be a good thing to use the alpha
status for any 1st release.

An alpha release costs nothing. Ie a 0.1 alpha.

pierre

Just as an FYI: the version number needs to include the patch level as
well. So you guys should actually be talking about:
0.6.0 and 1.0.0 etc.

regards,
Lukas Smith
smith@backendmedia.com
_______________________________
BackendMedia
www.backendmedia.com
berlin@backendmedia.com

Linn Zwoch Smith GbR
Pariser Str. 44
D-10707 Berlin

Tel +49 30 83 22 50 00
Fax +49 30 83 22 50 07

And also a "alpha1"-addition which would make it 0.6.0alpha1 ??
I'm just reading that again from
http://pear.php.net/group/docs/20040226-vn.php
and I must say I'm a bit surprised why this complicated way was
chosen. Why e.g. alpha2? Why not 0.6.1alpha?

PS: This is not "critism against a group-discussion". Maybe I simply
got things wrong ...

Stefan

The reason why the state was added to the version name is as follows:
- it is php standard to do this for RC state (also there is no state RC
in the package.dtd)
- once you update to a new major version you start off with 2.0.0alpha1
for example, then you continue with 2.0.0alpha2, possibly followed by
2.0.0beta1 and then 2.0.0RC1, 2.0.0RC2 and then 2.0.0
you can critize the group .. we are humans and can make mistakes :-)

regards,
Lukas Smith
smith@backendmedia.com
_______________________________
BackendMedia
www.backendmedia.com
berlin@backendmedia.com

Linn Zwoch Smith GbR
Pariser Str. 44
D-10707 Berlin

Tel +49 30 83 22 50 00
Fax +49 30 83 22 50 07

One question, the version numbers stock are unlimited, why start
with 0.6.0? :)

piere

Yeah, seems you got the idea :-)) Why not start with "0.6.0" in state
alpha and then moving to a "0.6.1" with state beta or something.
I can pretty much understand the reasons why it *might* be useful to
add the state to the name. E.g. 0.6.0alpha, 0.6.1beta. But imho this
is already reflected in the field containing the package state.
At least, I see no sense in making 0.6.0alpha2 instead of 0.6.1alpha
:-))

PS: Pierre, weren't you also part of the group that agreed upon such
a standard? :-))) Just kidding ...

Stefan

You got me wrong :)

I'm asking why you start with 0.6.0 status:(alpha?) and not 0.1.0
status alpha. The later is riskless and allow QA, you or any other
to ask for the required changes (if any).

pierre

Again you're confusing me :-)) What did you mean by the "required
changes"? So is alpha1 and alpha2 useful (and I simply didn't get it)
or not? From your point of view "we have enough numbers" - so we can
easily use the patchlevel-value (0.0.x) to could the alpha/beta
releases.
The other question was why we need extra alpha/beta-indicators since
this is already in the package-state. Why not release a "2.0.0" in
state alpha and later release a "2.0.3" or something as stable? This
would save us from a lot of pain with alpha1, beta1, RC1, pl1 and
similar :-(

Stefan

I'm not discussing this document.

I'm talking about how you may release the 1st package. Having the
status alpha allow you to fix any kind of issue, this is not the
case with beta or stable. Then I suggest to use 0.1.0 as the 1st
version.

pierre

Hi,
Because the PEAR version was not the initial version. I started the
proposal when 0.5 had been finished...

Of course I could also release it as 1.0.0alpha1

Stephan

No

pierre

Hi,
Why not? When should I switch to version 1.0?
The API is quite stable, there will be feature additions but I will not
remove any public methods or properties. My main proble is that I'm not
sure on how to determine the point I should (or am allowed) to switch to
1.0.0....

I think the whole version naming thing will complicate PEAR. If a
typical user sees a package that is 0.1, he will always think that this
package is immature and lacks a lot of the planned functionality.

We have to make sure that people understand why the version of a package
is as it is. And for this, the PEAR Group document is not sufficient.

Stephan

Hi Stephan,

I think that the typical user should be aware of how field-tested a
package is by the stability. If a package is released that has not been
field-tested, there is a chance that the API will need to change when
unanticipated problems are found. For most software packages, major
users like ISPs wait until a version has been tested by users for
months, and provide a patched version (this is what my webhost does with
PHP, it always lags). PEAR's strength is that this becomes pretty much
unnecessary, of course.

Obviously your package is much simpler than PHP, so you have the right
to do what is best for the package. I think you'll find that the alpha
tag doesn't hamper the users who you'll want to do the most testing.
Just check the download statistics of alpha packages that already exist.

From my perspective, it's more of a protection of the meaning of
stable, so if you release a beta, that's fine, it just freezes the API
instantly. You'll find yourself rather quickly releasing XML_XUL2 if
the API does need to be changed, and that would suck far more than
calling the initial release alpha :).

Here's my disclaimer: every package is unique and I'm not the author of
XML_XUL, please take my suggestions as friendly suggestions, and not
annoying commands, if possible :).

Greg

Stephan Schmidt wrote: