Return-Path: X-Original-To: apmail-maven-users-archive@www.apache.org Delivered-To: apmail-maven-users-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id A26EB10C81 for ; Fri, 3 Jan 2014 17:20:39 +0000 (UTC) Received: (qmail 5320 invoked by uid 500); 3 Jan 2014 17:20:34 -0000 Delivered-To: apmail-maven-users-archive@maven.apache.org Received: (qmail 5226 invoked by uid 500); 3 Jan 2014 17:20:32 -0000 Mailing-List: contact users-help@maven.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Help: List-Post: List-Id: "Maven Users List" Reply-To: "Maven Users List" Delivered-To: mailing list users@maven.apache.org Received: (qmail 5212 invoked by uid 99); 3 Jan 2014 17:20:31 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 03 Jan 2014 17:20:31 +0000 X-ASF-Spam-Status: No, hits=2.2 required=5.0 tests=HTML_MESSAGE,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (nike.apache.org: local policy) Received: from [24.37.79.202] (HELO smtp.artifact-software.com) (24.37.79.202) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 03 Jan 2014 17:20:24 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by smtp.artifact-software.com (Postfix) with ESMTP id CB2356A7916; Fri, 3 Jan 2014 12:20:02 -0500 (EST) X-Virus-Scanned: amavisd-new at artifact-software.com Received: from smtp.artifact-software.com ([127.0.0.1]) by localhost (smtp.artifact-software.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id KOD69m1zJNdi; Fri, 3 Jan 2014 12:19:37 -0500 (EST) Received: from [192.168.3.170] (unknown [192.168.3.170]) by smtp.artifact-software.com (Postfix) with ESMTP id 506EF6A76F2; Fri, 3 Jan 2014 12:19:37 -0500 (EST) Message-ID: <52C6F128.1000702@artifact-software.com> Date: Fri, 03 Jan 2014 12:19:36 -0500 From: Ron Wheeler Reply-To: rwheeler@artifact-software.com Organization: Artifact Software User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.2.0 MIME-Version: 1.0 To: Maven Users List , Maven Developers List Subject: Re: New site content References: <52C6E4D4.1040707@artifact-software.com> In-Reply-To: Content-Type: multipart/alternative; boundary="------------050205040202030407060408" X-Virus-Checked: Checked by ClamAV on apache.org --------------050205040202030407060408 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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 > 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 > >: > > On 3 January 2014 15:17, Robert Scholte > > 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.connolly@gmail.com > >: > > > Just in case it wasn't clear... I'm looking for > comments and feedback > > > > On 3 January 2014 14:35, Stephen Connolly > >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-unsubscribe@maven.apache.org > > For additional commands, e-mail: users-help@maven.apache.org > > > > > > -- > Ron Wheeler > President > Artifact Software Inc > email: rwheeler@artifact-software.com > > skype: ronaldmwheeler > phone: 866-970-2435, ext 102 > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: users-unsubscribe@maven.apache.org > > For additional commands, e-mail: users-help@maven.apache.org > > > -- Ron Wheeler President Artifact Software Inc email: rwheeler@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102 --------------050205040202030407060408--