You are viewing a plain text version of this content. The canonical link for it is here.
Posted to zeta-dev@incubator.apache.org by Maxime Thomas <ma...@gmail.com> on 2011/01/11 12:26:12 UTC
[zeta-dev] Documentation
Hi,
As started on Twitter with @arno_u_loginlux, we think that the ezc / azc
documentation can be improved in several ways.
As an end-user of this library / framework, I like the spirit of it and the
way you can quickly adopt a component and use it in your software.
However, regarding the documentation, for more than one year that I'm using
mostly all components and I think we can complete it / improve it.
I list here my thoughts about the documentation and you may feel free to add
or challenge each point. In my opinion, each component have to get the
following piece of information (if it hasn't yet) :
- a schema : a visual way to understand the concepts underneath. We get
it one for MVC which was cool because it's I guess the most complex one but
I think it's not enough.
- a list of examples, which can be like the PHP documentation, user
contributed. The aim is to provide example of the real life or specific use
that are not specified in the built-in specification.
- a method that can be used to easily debug the code. Typical dev does
not want to get in the ezc code but just use it. It's a bit problematic to
know if there's a real bug inside the component or if it's a bad usage we
are making of it. For example, I use PersistentObject and I would like to
know why the find query returns me nothing. In the documentation, there's no
clue to that could help me to resolve my probleme. And also, there's no way
to print the $q->getQuery() without hacking PersistentObject. Maybe we must
consider the fact to create a false dependancy to Debug, disabled by
default.
By resolving this, I guess we will increase the number of user.
I know that it is a significant effort on documentation but it will have a
great effect on users.
--
Maxime
maxime.thomas@wascou.org | www.wascou.org | http://twitter.com/wascou
Re: [zeta-dev] Documentation
Posted by Maxime Thomas <ma...@gmail.com>.
2011/1/12 Maxime Thomas <ma...@gmail.com>
>
>
> 2011/1/12 Gaetano Giunta <gi...@gmail.com>
>
> James Pic wrote:
>>
>>> Hi all,
>>>
>>> On Wed, Jan 12, 2011 at 8:46 AM, Christian Grobmeier
>>> <gr...@gmail.com> wrote:
>>>
>>>> - a method that can be used to easily debug the code. ... For
>>>>>> example, I use PersistentObject and I would like
>>>>>> to
>>>>>> know why the find query returns me nothing. In the documentation,
>>>>>> there's no
>>>>>> clue to that could help me to resolve my probleme. And also,
>>>>>> there's no
>>>>>> way
>>>>>> to print the $q->getQuery() without hacking PersistentObject.
>>>>>>
>>>>> Isn't it possible by just setting a breakpoint and without hacking ?
>>>
>>> Maybe we
>>>>>> must
>>>>>> consider the fact to create a false dependancy to Debug, disabled
>>>>>> by
>>>>>> default.
>>>>>>
>>>>> What would be the benefits of that over xdebug ?
>>>
>>> I insist for your own good, maybe the source of your problem is not
>>> specific to the components... are you sure you're using xdebug
>>> correctly ?
>>>
>> A pertinent question: is xdebug considered a strict requirement for doing
>> zetaC development?
>>
>> Regards
>>>
>>> James
>>>
>>> --
>>> http://jamespic.info
>>> Customer is king - Le client est roi - El cliente es rey.
>>>
>>>
>>
> I can see a limitation of the use of XDebug, but maybe you can correct me
> and teach me how to solve this one :
>
> I'm developping under Windows with Eclipse like most of the dev and I'm
> running my LAMP stack inside a VM with.
> My project is a shared folder mounted via network.
> XDebug can help me to debug the Apache PHP script but not the cli ones with
> my configuration ?
>
> If it does the trick, we can just write this down and put it in a FAQ /
> side subjects.
>
> --
> Maxime
> maxime.thomas@wascou.org | www.wascou.org | http://twitter.com/wascou
>
>
>
Finally, comparing it to eZPublish documentation, I think AZC lacks of real
community way to get side reference article (a shared one).
It may be resumed as a link page in the current website.
--
Maxime
maxime.thomas@wascou.org | www.wascou.org | http://twitter.com/wascou
Re: [zeta-dev] Documentation
Posted by Maxime Thomas <ma...@gmail.com>.
2011/1/12 Gaetano Giunta <gi...@gmail.com>
> James Pic wrote:
>
>> Hi all,
>>
>> On Wed, Jan 12, 2011 at 8:46 AM, Christian Grobmeier
>> <gr...@gmail.com> wrote:
>>
>>> - a method that can be used to easily debug the code. ... For example,
>>>>> I use PersistentObject and I would like
>>>>> to
>>>>> know why the find query returns me nothing. In the documentation,
>>>>> there's no
>>>>> clue to that could help me to resolve my probleme. And also, there's
>>>>> no
>>>>> way
>>>>> to print the $q->getQuery() without hacking PersistentObject.
>>>>>
>>>> Isn't it possible by just setting a breakpoint and without hacking ?
>>
>> Maybe we
>>>>> must
>>>>> consider the fact to create a false dependancy to Debug, disabled by
>>>>> default.
>>>>>
>>>> What would be the benefits of that over xdebug ?
>>
>> I insist for your own good, maybe the source of your problem is not
>> specific to the components... are you sure you're using xdebug
>> correctly ?
>>
> A pertinent question: is xdebug considered a strict requirement for doing
> zetaC development?
>
> Regards
>>
>> James
>>
>> --
>> http://jamespic.info
>> Customer is king - Le client est roi - El cliente es rey.
>>
>>
>
I can see a limitation of the use of XDebug, but maybe you can correct me
and teach me how to solve this one :
I'm developping under Windows with Eclipse like most of the dev and I'm
running my LAMP stack inside a VM with.
My project is a shared folder mounted via network.
XDebug can help me to debug the Apache PHP script but not the cli ones with
my configuration ?
If it does the trick, we can just write this down and put it in a FAQ / side
subjects.
--
Maxime
maxime.thomas@wascou.org | www.wascou.org | http://twitter.com/wascou
Re: [zeta-dev] Documentation
Posted by Gaetano Giunta <gi...@gmail.com>.
James Pic wrote:
> Hi all,
>
> On Wed, Jan 12, 2011 at 8:46 AM, Christian Grobmeier
> <gr...@gmail.com> wrote:
>>>> - a method that can be used to easily debug the code. ... For example, I use PersistentObject and I would like
>>>> to
>>>> know why the find query returns me nothing. In the documentation,
>>>> there's no
>>>> clue to that could help me to resolve my probleme. And also, there's no
>>>> way
>>>> to print the $q->getQuery() without hacking PersistentObject.
> Isn't it possible by just setting a breakpoint and without hacking ?
>
>>>> Maybe we
>>>> must
>>>> consider the fact to create a false dependancy to Debug, disabled by
>>>> default.
> What would be the benefits of that over xdebug ?
>
> I insist for your own good, maybe the source of your problem is not
> specific to the components... are you sure you're using xdebug
> correctly ?
A pertinent question: is xdebug considered a strict requirement for doing zetaC development?
> Regards
>
> James
>
> --
> http://jamespic.info
> Customer is king - Le client est roi - El cliente es rey.
>
Re: [zeta-dev] Documentation
Posted by James Pic <ja...@gmail.com>.
Hi all,
On Wed, Jan 12, 2011 at 8:46 AM, Christian Grobmeier
<gr...@gmail.com> wrote:
>
> >> - a method that can be used to easily debug the code. ... For example, I use PersistentObject and I would like
> >> to
> >> know why the find query returns me nothing. In the documentation,
> >> there's no
> >> clue to that could help me to resolve my probleme. And also, there's no
> >> way
> >> to print the $q->getQuery() without hacking PersistentObject.
Isn't it possible by just setting a breakpoint and without hacking ?
> >> Maybe we
> >> must
> >> consider the fact to create a false dependancy to Debug, disabled by
> >> default.
> >
What would be the benefits of that over xdebug ?
I insist for your own good, maybe the source of your problem is not
specific to the components... are you sure you're using xdebug
correctly ?
Regards
James
--
http://jamespic.info
Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
Posted by Christian Grobmeier <gr...@gmail.com>.
>> - a method that can be used to easily debug the code. ... For example, I use PersistentObject and I would like
>> to
>> know why the find query returns me nothing. In the documentation,
>> there's no
>> clue to that could help me to resolve my probleme. And also, there's no
>> way
>> to print the $q->getQuery() without hacking PersistentObject. Maybe we
>> must
>> consider the fact to create a false dependancy to Debug, disabled by
>> default.
>
> I have no real proposal to make for debugging helpers, but am interested in
> any that might be given...
>
Usually logging systems are being used. In this case log4php could
generate warnings if configured. But this would require to depend on
log4php. Of course zeta can provide a mock object which does nothing,
in case log4php classes can not be found. This also will keep up the
speed in production systems
Dependency Injection can be used to inject some kind of a logging
object. But... how many people are there who can use DI? Plain and
simple logging will do the job for most people.
Re: [zeta-dev] Documentation
Posted by James Pic <ja...@gmail.com>.
On Wed, Jan 12, 2011 at 12:26 PM, Gaetano Giunta
<gi...@gmail.com> wrote:
> James Pic wrote:
>>
>> What lib/program/framework does it better than the components and why ?
>
> Completely unrelated, but the Delphi VCL is the lib I have the fondest
> memories of.
>
Thanks for your great input!
I've picked a random documentation page:
http://delphi.wikia.com/wiki/Create_Your_Own_Paint_Program
I must admit, that a tutorial to create a paint program, is way more
exciting than for
example the hello world tutorial.
On Wed, Jan 12, 2011 at 1:44 PM, Maxime Thomas <ma...@gmail.com> wrote:
> 2011/1/12 Gaetano Giunta <gi...@gmail.com>
>
>> James Pic wrote:
>>
>>> On Wed, Jan 12, 2011 at 8:46 AM, Christian Grobmeier
>>> <gr...@gmail.com> wrote:
>>>
>>> Maybe we
>>>>>> must
>>>>>> consider the fact to create a false dependancy to Debug, disabled by
>>>>>> default.
>>>>>>
>>>>> What would be the benefits of that over xdebug ?
>>>
>>> I insist for your own good, maybe the source of your problem is not
>>> specific to the components... are you sure you're using xdebug
>>> correctly ?
>>>
>> A pertinent question: is xdebug considered a strict requirement for doing
>> zetaC development?
>>
>>
> I can see a limitation of the use of XDebug, but maybe you can correct me
> and teach me how to solve this one :
>
> I'm developping under Windows with Eclipse like most of the dev and I'm
> running my LAMP stack inside a VM with.
> My project is a shared folder mounted via network.
> XDebug can help me to debug the Apache PHP script but not the cli ones with
> my configuration ?
>
> If it does the trick, we can just write this down and put it in a FAQ / side
> subjects.
There are many ways, please overview the official documentation before
continuing:
http://www.xdebug.org/docs/remote
You should set:
xdebug.remote_enable="1"
xdebug.remote_host="the ip of your machine that has the IDE"
Using your favorite IDE, you can set breakpoints in advance in files.
That said, xdebug_break() often proves useful as well.
Also, you can set xdebug.remote_autostart="1"
if you want to make sure it starts every time php starts.
I think the trickiest part of xdebug remote debugging is to understand that:
0) xdebug.so is the DBGP *client*, it must connect to the server
1) your IDE is the DBGP *server*, it must listen for incoming client connections
My last advice is: use strace (or alternative from your OS) for troubleshooting.
It's important to know if:
0) the client (your http server) connects to the right ip on the right
port (default is 9000)
1) the server listens on the right ip (ie rather 0.0.0.0 than
127.0.0.1) and port
>
> A relevant question: is xdebug considered a strict requirement for doing
> zetaC development?
Depends. Most of the experienced coders will consider a debugger as a
strict requirement for comfortable development (amongst other stuff like TTD,
SCRUM etc ...).
It is however required for ZetaC core development, ie. if you want to contribute
back your features, bugfixes etc ...
I however, as a professional coder like probably every one on this
list, am payed
to write code and to maintain it and to debug it so at the end of the day i'm
actually payed to use a debugger. It has been that way for years. And man, I
love working with xdebug and the components (amongst other things like
vim or git).
Thus, as a professional, i'd expect you to be paid to use a debugger instead of
trying to log/print/output debug info with temporary codes.
That said, i don't care if xdebug is a requirement or whatnot. If you
my friend, need
some assistance with using xdebug, then feel free to just pop in #zetacomponents
or query me "jpic" on freenode, like Derick and others from the powerful eZC
community helped me during years ;)
So i'll return the question: should it the role of ZetaC to document good coding
practices such as usage of a VCS or a debugger to users ?
I'd tend to say: why not after all. Diversifying our activity could
improve the end
user experience. *BUT* in that case, should it really be the
responsibility of the
Apache Zeta Components project ? Or should another project document and try
(thus, try to unify) actual PHP development with "the full gear" ?
> In short, PhpUnit just failed to test Zeta's exceptions objects, and neededI'd say yes.
> an explicit bootstrap to do the job. UnitTests provides such a bootstrap
> file, unfortunatly UnitTest is'nt part of the Zeta's PEAR packages yet, and
> I just missed this point. I don't know if including the UnitTest into PEAR
> is roadmapped for now. I think newbie dev like me need a short paragraph in
> the Zeta tutorials, something like "How to implement PhpUnit tests into your
> Zeta-based App"
Are you talking about this 15-liner ?
http://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/UnitTest/src/bootstrap.php
Needless to say, you can check php.net/function_name or
zetac.org/class_name to access
documentation of pretty much everything in this file.
In fine, don't you think that we should actually document how to
develop with Zeta Components,
rather than documenting the components themselves ?
Why should the docs cover xdebug and not subversion or even filesystems ?
Maybe we want to consider writing a book that would guide the user
through the realisation of
a project, pretty much like djangobook, delphi vlc, "pragmatic guide
to javascript".
It does sound like a lot of work, but i'd agree it's worth a shot ...
> Otoh debugging Symfony for 3 days brought me to the conclusion that the
> smartness of the code that Fabien likes to write puts it beyond mere mortals
> comprehension, and no advantages gained in reduced lines of code,
> extensibility and execution speed are worth it in the end (this was
> confirmed by reading his slide set about dependency injection in php 5.3).
>
> But maybe it's just me getting old and having a hard time learning new
> styles / paradigms... :-)
Thanks for this great feedback as well, you totally made my day :D
--
http://jamespic.info
Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
Posted by Gaetano Giunta <gi...@gmail.com>.
James Pic wrote:
> Hi Gaetano
>
> On Tue, Jan 11, 2011 at 10:15 PM, Gaetano Giunta
> <gi...@gmail.com> wrote:
>> To me, the way the components work often feels like blackmagick: sometimes
>> it is logical, but more often it's just like incantations. The example
>> spells given in the docs are fine, but as soon as you stray a little bit
>> from those, you're on your own - either it works at the very first try or it
>> becomes a thankless test/change/repeat loop (eg. sometimes a certain mix of
>> options work, and another mix does not work, or some methods have to be
>> invoked in a particular order).
> Looks like a hacker thing :D
>
> Isn't that how pretty much all libs, frameworks, and programming
> languages work in general ?
Sure enough.
Surely everybody on this list is knowledgeable about good api design principles, so I'll not spend time talking about simplicity, consistency, discoverability,
resistence to misuse, absence of side effects.
I guess in the end it's a matter of coding style / personal preferences for 50% and a measurable thing for 50%.
> What lib/program/framework does it better than the components and why ?
Completely unrelated, but the Delphi VCL is the lib I have the fondest memories of.
Otoh debugging Symfony for 3 days brought me to the conclusion that the smartness of the code that Fabien likes to write puts it beyond mere mortals
comprehension, and no advantages gained in reduced lines of code, extensibility and execution speed are worth it in the end (this was confirmed by reading his
slide set about dependency injection in php 5.3).
But maybe it's just me getting old and having a hard time learning new styles / paradigms... :-)
> Regards
>
> James
>
Re: [zeta-dev] Documentation
Posted by James Pic <ja...@gmail.com>.
Hi Gaetano
On Tue, Jan 11, 2011 at 10:15 PM, Gaetano Giunta
<gi...@gmail.com> wrote:
> To me, the way the components work often feels like blackmagick: sometimes
> it is logical, but more often it's just like incantations. The example
> spells given in the docs are fine, but as soon as you stray a little bit
> from those, you're on your own - either it works at the very first try or it
> becomes a thankless test/change/repeat loop (eg. sometimes a certain mix of
> options work, and another mix does not work, or some methods have to be
> invoked in a particular order).
Looks like a hacker thing :D
Isn't that how pretty much all libs, frameworks, and programming
languages work in general ?
What lib/program/framework does it better than the components and why ?
Regards
James
--
http://jamespic.info
Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
Posted by Maxime Thomas <ma...@gmail.com>.
2011/1/11 Gaetano Giunta <gi...@gmail.com>
> Maxime Thomas wrote:
>
>> Hi,
>>
>> As started on Twitter with @arno_u_loginlux, we think that the ezc / azc
>> documentation can be improved in several ways.
>>
>> As an end-user of this library / framework, I like the spirit of it and
>> the
>> way you can quickly adopt a component and use it in your software.
>>
>> However, regarding the documentation, for more than one year that I'm
>> using
>> mostly all components and I think we can complete it / improve it.
>>
>> I list here my thoughts about the documentation and you may feel free to
>> add
>> or challenge each point. In my opinion, each component have to get the
>> following piece of information (if it hasn't yet) :
>>
>> - a schema : a visual way to understand the concepts underneath. We get
>> it one for MVC which was cool because it's I guess the most complex one
>> but
>> I think it's not enough.
>> - a list of examples, which can be like the PHP documentation, user
>> contributed. The aim is to provide example of the real life or specific
>> use
>> that are not specified in the built-in specification.
>> - a method that can be used to easily debug the code. Typical dev does
>> not want to get in the ezc code but just use it. It's a bit problematic
>> to
>> know if there's a real bug inside the component or if it's a bad usage
>> we
>> are making of it. For example, I use PersistentObject and I would like
>> to
>> know why the find query returns me nothing. In the documentation,
>> there's no
>> clue to that could help me to resolve my probleme. And also, there's no
>> way
>> to print the $q->getQuery() without hacking PersistentObject. Maybe we
>> must
>> consider the fact to create a false dependancy to Debug, disabled by
>> default.
>>
> That's a tough problem, but I concur with the last point.
>
> To me, the way the components work often feels like blackmagick: sometimes
> it is logical, but more often it's just like incantations. The example
> spells given in the docs are fine, but as soon as you stray a little bit
> from those, you're on your own - either it works at the very first try or it
> becomes a thankless test/change/repeat loop (eg. sometimes a certain mix of
> options work, and another mix does not work, or some methods have to be
> invoked in a particular order).
> As far as I can tell, this is at least in part a fruit of the
> design/architecture of the components: with the division of tasks in so many
> small classes and the heavy usage of subclasses and magic methods (getters,
> setters etc), following the logic trough the code is not the easiest task.
> The upside being that more often than not, you will be able to solve your
> problem by creating a subclass with a one-liner fix in a single method!
>
> I have no real proposal to make for debugging helpers, but am interested in
> any that might be given...
>
> bye
> Gaetano
>
> By resolving this, I guess we will increase the number of user.
>> I know that it is a significant effort on documentation but it will have a
>> great effect on users.
>>
>>
>
The first point was just to document those solutions which can help you
debugging what you've done.
Of course, we can use inheritance, but it can be a problem for some classes
that check the class type (instance of).
Maybe we can just list what we want to debug then think to a mechanism. My
first think goes to everything which can query (Db, LDAP, Search and so on).
--
Maxime
maxime.thomas@wascou.org | www.wascou.org | http://twitter.com/wascou
Re: [zeta-dev] Documentation
Posted by Gaetano Giunta <gi...@gmail.com>.
Maxime Thomas wrote:
> Hi,
>
> As started on Twitter with @arno_u_loginlux, we think that the ezc / azc
> documentation can be improved in several ways.
>
> As an end-user of this library / framework, I like the spirit of it and the
> way you can quickly adopt a component and use it in your software.
>
> However, regarding the documentation, for more than one year that I'm using
> mostly all components and I think we can complete it / improve it.
>
> I list here my thoughts about the documentation and you may feel free to add
> or challenge each point. In my opinion, each component have to get the
> following piece of information (if it hasn't yet) :
>
> - a schema : a visual way to understand the concepts underneath. We get
> it one for MVC which was cool because it's I guess the most complex one but
> I think it's not enough.
> - a list of examples, which can be like the PHP documentation, user
> contributed. The aim is to provide example of the real life or specific use
> that are not specified in the built-in specification.
> - a method that can be used to easily debug the code. Typical dev does
> not want to get in the ezc code but just use it. It's a bit problematic to
> know if there's a real bug inside the component or if it's a bad usage we
> are making of it. For example, I use PersistentObject and I would like to
> know why the find query returns me nothing. In the documentation, there's no
> clue to that could help me to resolve my probleme. And also, there's no way
> to print the $q->getQuery() without hacking PersistentObject. Maybe we must
> consider the fact to create a false dependancy to Debug, disabled by
> default.
That's a tough problem, but I concur with the last point.
To me, the way the components work often feels like blackmagick: sometimes it is logical, but more often it's just like incantations. The example spells given
in the docs are fine, but as soon as you stray a little bit from those, you're on your own - either it works at the very first try or it becomes a thankless
test/change/repeat loop (eg. sometimes a certain mix of options work, and another mix does not work, or some methods have to be invoked in a particular order).
As far as I can tell, this is at least in part a fruit of the design/architecture of the components: with the division of tasks in so many small classes and the
heavy usage of subclasses and magic methods (getters, setters etc), following the logic trough the code is not the easiest task. The upside being that more
often than not, you will be able to solve your problem by creating a subclass with a one-liner fix in a single method!
I have no real proposal to make for debugging helpers, but am interested in any that might be given...
bye
Gaetano
> By resolving this, I guess we will increase the number of user.
> I know that it is a significant effort on documentation but it will have a
> great effect on users.
>
Re: [zeta-dev] Documentation
Posted by Ronan Guilloux <ro...@gmail.com>.
2011/1/11 James Pic <ja...@gmail.com>
> On Tue, Jan 11, 2011 at 2:39 PM, Ronan Guilloux <ronan.guilloux@gmail.com
> >wrote:
>
(...)
Adding cronjobs is easy, but this should be documented or shown in an
> > example a day, since it's a common need.
>
> Do you mean, how to setup a cronjob and post-commit hooks ?
> What do you think would be zetacomponents-specific about that ?
>
=> Sorry I wasn't clear : Just setting up a simple runcronjob.php to be
called from the crontab, with daily/weekly/frequent options calls (the
ezpublish way, I mean). This just needs to understand the AZC's autoload
environment, so no difficults here.
(...)
>
> > The main difficult I encountered was to implement PhpUnit easely. Some
> > weeks
> > ago I crawled the all Zeta Components example apps (here :
> > http://goo.gl/Xg828) but I didn't found any app implementing PhpUnit
> yet.
> > PhpUnit doc about bootstrapping was not clear enough to me.
>
>
> Did you consider Arbit project sources ? It's built upon ZetaComponents and
> uses PHPUnit for testing.
>
>
Yes, and I now used it, and started to become an Arbit fan ! But I often run
my PhpUnitTests the CLI-way, in my own dev env, before sending my commits to
the CI server.
> >
> UnitTest barely wraps around PHPUnit, providing a few features that are
> specific to components tests.
>
> Which of its features do you need in your project ?
>
>
I just missed the PHPunit bootstrap file, provided in the UnitTest component
> Implemeting PhpUnit into Zeta Components needs a tutorial
> >
>
> Did you consider:
>
> The tutorial to install PHPUnit:
> http://www.phpunit.de/manual/current/en/installation.html
> The tutorial to writing tests:
> http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html
> The tutorial automating builds:
> http://www.phpunit.de/manual/current/en/build-automation.html
> The tutorial to continuous integration by Arbit:
>
> http://tracker.arbitracker.org/arbit/documentation/view/ContinuousIntegration
>
>
I'd candidate although i'd need your opinion concerning the following
> questions:
>
> - do these tutorial contain the informations you are looking for ?
> - if not, what other information do you need ?
> - if so, why, where and how should the components cover these topics ?
>
>
In short, PhpUnit just failed to test Zeta's exceptions objects, and needed
an explicit bootstrap to do the job. UnitTests provides such a bootstrap
file, unfortunatly UnitTest is'nt part of the Zeta's PEAR packages yet, and
I just missed this point. I don't know if including the UnitTest into PEAR
is roadmapped for now. I think newbie dev like me need a short paragraph in
the Zeta tutorials, something like "How to implement PhpUnit tests into your
Zeta-based App"
Thanks to you James,
Ronan
Re: [zeta-dev] Documentation
Posted by James Pic <ja...@gmail.com>.
On Tue, Jan 11, 2011 at 2:39 PM, Ronan Guilloux <ro...@gmail.com>wrote:
> +1 for all that Maxime wrote about.
>
> But my very first need & tweet was simpler : How to add a set of cronjobs,
> and how to add a PhpUnit test suite into a HelloMvc-like website (cf.
> http://goo.gl/TvXVn) .
>
Adding cronjobs is easy, but this should be documented or shown in an
> example a day, since it's a common need.
Do you mean, how to setup a cronjob and post-commit hooks ?
What do you think would be zetacomponents-specific about that ?
> I'll try to improve my frenchy
> globish english a write a decent tutorial about that, somehwere, some day.
>
>
Yeah I know, we French are the worst English speakers in the world :D
> The main difficult I encountered was to implement PhpUnit easely. Some
> weeks
> ago I crawled the all Zeta Components example apps (here :
> http://goo.gl/Xg828) but I didn't found any app implementing PhpUnit yet.
> PhpUnit doc about bootstrapping was not clear enough to me.
Did you consider Arbit project sources ? It's built upon ZetaComponents and
uses PHPUnit for testing.
I've uploaded the sources of the last app framework i coded with the
components, it uses PHPUnit for testing: https://github.com/jpic/zetamad
but reading the
> UnitTest bootstrap.php file (found here : http://goo.gl/nH96H) helped a
> lot
> and it finally did the job. Unfortunatly, while UnitTest is listed in the
> official Zeta Components docs, it's a broken link in the official doc (here
> : http://goo.gl/wKHnN).
>
>
UnitTest barely wraps around PHPUnit, providing a few features that are
specific to components tests.
Which of its features do you need in your project ?
> Implemeting PhpUnit into Zeta Components needs a tutorial
>
Did you consider:
The tutorial to install PHPUnit:
http://www.phpunit.de/manual/current/en/installation.html
The tutorial to writing tests:
http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html
The tutorial automating builds:
http://www.phpunit.de/manual/current/en/build-automation.html
The tutorial to continuous integration by Arbit:
http://tracker.arbitracker.org/arbit/documentation/view/ContinuousIntegration
I'd candidate although i'd need your opinion concerning the following
questions:
- do these tutorial contain the informations you are looking for ?
- if not, what other information do you need ?
- if so, why, where and how should the components cover these topics ?
Regards
James
--
http://jamespic.info
Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
Posted by Ronan Guilloux <ro...@gmail.com>.
+1 for all that Maxime wrote about.
But my very first need & tweet was simpler : How to add a set of cronjobs,
and how to add a PhpUnit test suite into a HelloMvc-like website (cf.
http://goo.gl/TvXVn) .
Adding cronjobs is easy, but this should be documented or shown in an
example a day, since it's a common need. I'll try to improve my frenchy
globish english a write a decent tutorial about that, somehwere, some day.
The main difficult I encountered was to implement PhpUnit easely. Some weeks
ago I crawled the all Zeta Components example apps (here :
http://goo.gl/Xg828) but I didn't found any app implementing PhpUnit yet.
PhpUnit doc about bootstrapping was not clear enough to me. but reading the
UnitTest bootstrap.php file (found here : http://goo.gl/nH96H) helped a lot
and it finally did the job. Unfortunatly, while UnitTest is listed in the
official Zeta Components docs, it's a broken link in the official doc (here
: http://goo.gl/wKHnN).
Implemeting PhpUnit into Zeta Components needs a tutorial, and I'm still a
PHPUnit rookie to write it.
Any candidate for that ?
--
Ronan Guilloux
2011/1/11 Maxime Thomas <ma...@gmail.com>
> Hi,
>
> As started on Twitter with @arno_u_loginlux, we think that the ezc / azc
> documentation can be improved in several ways.
>
> As an end-user of this library / framework, I like the spirit of it and the
> way you can quickly adopt a component and use it in your software.
>
> However, regarding the documentation, for more than one year that I'm using
> mostly all components and I think we can complete it / improve it.
>
> I list here my thoughts about the documentation and you may feel free to
> add
> or challenge each point. In my opinion, each component have to get the
> following piece of information (if it hasn't yet) :
>
> - a schema : a visual way to understand the concepts underneath. We get
> it one for MVC which was cool because it's I guess the most complex one
> but
> I think it's not enough.
> - a list of examples, which can be like the PHP documentation, user
> contributed. The aim is to provide example of the real life or specific
> use
> that are not specified in the built-in specification.
> - a method that can be used to easily debug the code. Typical dev does
> not want to get in the ezc code but just use it. It's a bit problematic
> to
> know if there's a real bug inside the component or if it's a bad usage we
> are making of it. For example, I use PersistentObject and I would like to
> know why the find query returns me nothing. In the documentation, there's
> no
> clue to that could help me to resolve my probleme. And also, there's no
> way
> to print the $q->getQuery() without hacking PersistentObject. Maybe we
> must
> consider the fact to create a false dependancy to Debug, disabled by
> default.
>
> By resolving this, I guess we will increase the number of user.
> I know that it is a significant effort on documentation but it will have a
> great effect on users.
>
> --
> Maxime
> maxime.thomas@wascou.org | www.wascou.org | http://twitter.com/wascou
>
Re: [zeta-dev] Documentation
Posted by Jerome Renard <je...@gmail.com>.
Hi James,
On Tue, Jun 7, 2011 at 12:27 PM, James Pic <ja...@gmail.com> wrote:
> Hello everybody,
>
> Kudos to Gavin for setting up my wiki access!
>
> Here is the table of contents i propose:
>
> https://cwiki.apache.org/confluence/display/ZETACOMP/Tutorial+TOC
>
> Any early thoughts you want to share ?
>
I Like :)
--
Jérôme Renard
http://39web.fr | http://jrenard.info | http://twitter.com/jeromerenard
Re: [zeta-dev] Documentation
Posted by James Pic <ja...@gmail.com>.
Hello everybody,
Kudos to Gavin for setting up my wiki access!
Here is the table of contents i propose:
https://cwiki.apache.org/confluence/display/ZETACOMP/Tutorial+TOC
Any early thoughts you want to share ?
Regards