https://cwiki.apache.org/confluence/display/MAVEN/Tutorial%3A+Maven+in+60+seconds
Still think that it is overly vague.
It would be easier to understand if the passive voice was eliminated.
Makes it clearer to understand what the developer has to do and what
maven is going to do while processing the POM.
The page should start with a statement saying that Maven builds
artifacts based on information provided by the developer.
You might want to talk about convention over configuration and how this
compares to Make or Ant.
"It all starts with a *project model"* ->"It all starts with a *project
model* that you create to tell Maven how you want your project (artifact?)."
/Note: reactor is just the name that Maven has given to the list of
modules that are being built
/Is module different than artifact? Are modules input or output?
See below for confusion about whether a reactor is a list or a thing
that does stuff./
/
The *packaging* of each module (artifact?) implies that modules are
output - should provide example "such as jar, war, tar or zip" (90
percent of cases?)
"The *dependencies* of each module" => "The dependencies that are
required to build, test and run the resulting project/module/artifact."
"Any additional *plugins* that are needed to build each module" => "Any
*plugins* that are needed to build each module."
What does additional mean to the new user?
Perhaps a sentence about default plug-ins that Maven includes
automatically might be useful but conceptually I don't think that the
distinction is useful at this point
"The lifecycle defines the default plugins that are used to build a
specific packaging. "
This is a bit startling to a new user even if it is correct.
It might be better to describe the lifecycle in terms of steps rather
than plug-ins.
It might also be worth being explicit that lifecycles are defined in
Maven not in the model.
These next 2 sentences need to be rewritten in the active case saying
that Maven does these things.
"The list of modules in the reactor is sorted in order to ensure that
any dependencies that will be created by the reactor will be built
before they are needed by other modules in the reactor
The *build plan* is then populated for each module using the lifecycle
and the plugin information from the model"
Build plan is not defined. Who creates it? What does it have in it
before it is populated? How many build plan are there - one for each
module?/ one for all?.
Should say that a single build plan is created that builds the
xxxx(components - no definition in the diagram of what the programmer
has programmed) in the correct sequence.
Maven then starts executing the build plan and building your project,
downloading dependencies that are not produced by the reactor.
A reactor was defined as a list of modules, now it is a thing that does
produced dependencies.
Final diagram is missing the output from the process.
It seems to say that Maven builds "Build Plans"(square box).
The developer wants an artifact out of this.
I hope that this helps.
Ron
On 03/01/2014 11:33 AM, Stephen Connolly wrote:
FYI here is my current plan for content:
https://cwiki.apache.org/confluence/display/MAVEN/New+Main+Site
On 3 January 2014 16:27, Ron Wheeler <rwhee...@artifact-software.com
<mailto:rwhee...@artifact-software.com>> wrote:
I agree with Robert's comment.
There is a danger that the page will become architecturally
elegant and will correctly describe all of the possible uses of
Maven but will be too obscure to be useful as a starting point for
a new person.
I actually think that the page is near complete from my point of
view... the remaining content is actually to provide links to pages
describing what each individual concept is and a link to the next
level of depth tutorial.
I what to draw only the outline of what maven does... on the other
hand, if you can think of an alternative set of content I am only too
happy to see such suggestions. If you need write access to the wiki,
shout out and I'll make it so (assuming you are a regular user/dev
list contributor)
It is sufficiently difficult to understand the basic concepts in
using Maven to create a simple jar with a single POM.
You are introducing a lot of new concepts:
-Lifecycle
-Dependencies
-Plug-ins
- Project model
that a person coming from make or Ant has to grasp.
Defining these and the relationships among them in a simple way is
sufficiently challenging without trying to abstract a sufficiently
general model to handle all of the edge cases.
The "Maven way" needs to be explained very simply rather than
conceptually complete.
Ron
On 03/01/2014 11:09 AM, Robert Scholte wrote:
Op Fri, 03 Jan 2014 16:46:33 +0100 schreef Stephen Connolly
<stephen.alan.conno...@gmail.com
<mailto:stephen.alan.conno...@gmail.com>>:
On 3 January 2014 15:17, Robert Scholte
<rfscho...@apache.org <mailto:rfscho...@apache.org>> wrote:
Hi,
I like the idea of images, however I would avoid a
graph to make something
clear for new Maven users.
Instead I'd prefer a linear model.
My first draft did not have the graph at the top...
perhaps it would be
better suited at the bottom ;-)
I think you should split the current model into pieces:
A project model contains:
- dependencies
- a build plan
- other project models ( you can call this the Droste
effect[1] )
I like to think of the project model as not just the root
pom.xml but all
the pom.xml files, so there is only one project model,
this should make
understanding how -pl, -am and -amd switches have their
effects
IMO these switches are way too detailed for a 60 sec tutorial.
I even think that a large group of the average Maven users
don't know these switches or use them.
- ...
There are several build-plans, namely: a build-plan
for jar, war, ear, etc.
Every build plan has a set of predefined plugins,
which you can adjust
(with switches?)
No there is one and only one build plan. We would have to
redefine build
plan everywhere else to be able to use it like that. There
is a lifecycle
binding for each packaging
Then buildplan is too abstract. With a real world example: the
buildplan for a house and a bike are completely different.
Unless you say: you have a design, some goods, you mix those
goods and you have your product.
Not a useful plan IMO.
At least keep the audience in mind: do they need to know the
actual implementation or do they first need to understand the
overall process. I think the latter is more important, even if
this conflicts a bit with the idiom used by experienced Maven
users.
What if we call it "build instructions" (per packaging type) ?
Now, what does Maven do?
Maven reads the build plan and executes it. Some steps
of the build plan
deliver products ( compiled classes, test results, a
package)
I think the reactor might be confusing at this level.
I want the 60sec tutorial to be the grand overview, the
next tutorial is a
5 minute one on how a .jar file gets built
Then you have a multi-module webapp tutorial at 10-15min
I want to reference all the core concepts from the 60
second overview even
if only briefly, that way people can come back to the
short page and say
"ahh yes that is where that fits in again"
my 2 cents,
Robert
[1] http://en.wikipedia.org/wiki/Droste_effect
Op Fri, 03 Jan 2014 15:41:15 +0100 schreef Stephen
Connolly <
stephen.alan.conno...@gmail.com
<mailto:stephen.alan.conno...@gmail.com>>:
Just in case it wasn't clear... I'm looking for
comments and feedback
On 3 January 2014 14:35, Stephen Connolly
<stephen.alan.conno...@gmail.com
<mailto:stephen.alan.conno...@gmail.com>>wrote:
OK, so to start working on new content I created
some pages on the wiki:
The first page is a 60 seconds overview of
Maven's build process
https://cwiki.apache.org/confluence/display/MAVEN/
Tutorial:+Maven+in+60+seconds
I am using icons because I want to have
subsequent pages give more detail
and use the iconography to enable people to
see what is being discussed
more easily
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@maven.apache.org
<mailto:users-unsubscr...@maven.apache.org>
For additional commands, e-mail: users-h...@maven.apache.org
<mailto:users-h...@maven.apache.org>
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
<mailto:rwhee...@artifact-software.com>
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@maven.apache.org
<mailto:users-unsubscr...@maven.apache.org>
For additional commands, e-mail: users-h...@maven.apache.org
<mailto:users-h...@maven.apache.org>
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
