On Fri, 2009-12-11 at 08:37 -0800, Cédric Beust ♔ wrote: > For what it's worth, I have had (and still do) the exact same > experience. > I am also in two minds about the user guide. Where it is good it is very good and very helpful where it is bad is is appalling.
I think the real problem with the user guide is that it is trying to be
a reference, a tutorial and an integration test. All the frustrations
people are mentioning are clear consequences of this conflict.
(I have more or less agreed to write an introductory book on using
Gradle but I haven't actually started yet as a flood of other things
have got in the way. :-(
>
> To me, the style guide is a bit similar to trying to learn a language
> by learning premade sentences. There is too much emphasis on "how"
> and not enough on "why".
Another part of the problem is that the user guide is being used as a
tool for driving integration testing and I am not sure the various
purposes are melded together appropriately just now.
> I think one of my main problems from the code snippets there is that I
> can't figure out which ones are "keywords" and which ones must be
> defined or included.
>
My problem of the moment in integTest, I am seeing traditional dynamic
language weirdnesses that using the symbol in some places things just
work and in others it all breaks.
> For example, the first real example (5.4):
>
> dependencies {
> compile group: 'commons-collections', name: 'commons-collections',
> version: '3.2'
> testCompile group: 'junit', name: 'junit', version: '4.+'
> }
> What is compile? And testCompile? They are not explained before.
> Actually, testCompile is never explained anywhere and that's the only
> place it ever appears in the doc.
>
compile and testCompile are the names of configurations that are defined
in the Java plugin.
>
> Every single code snippet in this documentation contains things like
> that and it's extremely frustrating. I want to like Gradle but you
> really need to make it much easier for people not interested in diving
> deep in the source...
>
This for me is an aspect of the fact that the code snippets are being
used for integration testing as well as documentation.
I am switching Gant from a Gant build to a Gradle build. Most of it
went trivially once I got the multi-project architecture in place (I
tried it in Maven and failed dismally, with Gradle it fell into place
quite nicely). However there are things that I find frustratingly
annoying so I understand your frustration.
The very worst outcome here would be for you to have a bad taste in your
mouth about Gradle. Even worse if you blog about that :-)
> As I said in a previous message, walking through a simple migration
> guide from ant would be a great start: pick a standard Java project
> with sources, tests, local jar dependencies, external jar dependencies
> and a packaging target, and step by step, show how to convert it to
> Gradle.
>
I think this is needed as an appendix to the user guide. Perhaps we can
use a wiki somewhere (Hans, Adam, where is an appropriate page to start
this?).
People put up project structures as children of the top level page and
then we can have the Ant build and/or Maven build as a child of that and
a Gradle build as another child.
This material would help immediately in that form and would also be
great input to the user guide and the book.
Another issue is that people need "known to work" examples of real
projects. I can offer the Gant project (Bazaar branch at lp:gant) and
my ADS library (which uses TestNG :-) (Bazaar branch at
http://www.russel.org.uk/Bazaar/ADS.)
I had an Ant build for Gant some time back and that will be there in the
history, ditto the ADS library. ADS still has a Maven build.
Hopefully this can move us on in a constructive, helpful and not
frustrating way.
--
Russel.
=============================================================================
Dr Russel Winder Partner
xmpp: [email protected]
Concertant LLP t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road, f: +44 8700 516 084 voip: sip:[email protected]
London SW11 1EN, UK m: +44 7770 465 077 skype: russel_winder
signature.asc
Description: This is a digitally signed message part
