git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@293440 13f79535-47bb-0310-9956-ffa450edef68

maven-site/src/site/apt/guides/getting-started/index.apt

@@ -110,21 +110,37 @@ m2 archetype:create -DgroupId=com.mycompany.app -DartifactId=my-app
   This is a very simple POM but still displays the key elements every POM contains so lets walk through each of them
   to familiarize you with the POM essentials:
 
-  * <<project>>
+  * <<project>> This is the top-level element in all Maven pom.xml files.
 
-  * <<modelVersion>>
+  * <<modelVersion>> This element indicates what version of the object model this POM is using. The version of the
+    model itself changes very infrequently but it is mandatory in order to ensure stability of use when and if
+    the Maven developers deem a change to the model necessasry.
 
-  * <<groupId>>
+  * <<groupId>> This element indicates the unique groupId of the organization or group that created the project.
+    The groupId is on of the key identifiers of a project and is typically based on the fully qualified
+    domain name of your organization. For example  <<<org.apache.maven.plugins>>> is the designated groupId for
+    all Maven plug-ins.
 
-  * <<artifactId>>
+  * <<artifactId>> This element indicates the unique base name of the primary artifact being generated by this project.
+    The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use
+    the artifactId as part of their final name. A typical artifact produced by would have the form
+    \<artifactId\>-\<version\>.\<extension\>.
 
-  * <<packaging>>
+  * <<packaging>> This element indicates the packing to be used by this artifact. This not only means if the artifact
+    produced is JAR, WAR, or EAR but can also indicate a specific lifecycle to use as part of the build process. This
+    is a topic we will deal with further on in the guide, just keep in mind the indicated packaging of a project
+    can play a part in customizing the build lifecycle.
 
-  * <<version>>
+  * <<version>> This element indicates the version of the artifact generated by the project. Maven goes a long way
+    to help you with version management and you will often see the <<<SNAPSHOT>>> designator in a version which
+    indicates a project is in a state of development. We will discuss the use of snapshots and how they work further
+    on in the guide.
 
-  * <<name>>
+  * <<name>> This element indicates the display name used for the project. This name is often used in Maven's
+    generated documentation.
 
-  * <<url>>
+  * <<url>> This element indicates where the project's site can be found. This url is often used in Maven's
+    generated documentation.
 
   []
 
@@ -201,13 +217,62 @@ Compiling 1 source file to /tmp/my-app/target/classes
  another standard convention employed by Maven. So, if you're a keen observer you'll notice that using the
  standard conventions the POM above is very small and you haven't explicity had to tell Maven where any of
  your sources are or where the output should go. By following the standard Maven conventions you can get
- a lot done with very little effort! Just as a comparison lets take a look at what you might have had to do
+ a lot done with very little effort! Just as a casual comparison lets take a look at what you might have had to do
  in {{{http://ant.apache.org}Ant}} to accomplish the same {{{../../ant/build-a1.xml}thing}}.
 
- Now this is simply to compile a single application source and the Ant script shown is pretty much the same
+ Now this is simply to compile a single tree of application sources and the Ant script shown is pretty much the same
  size as the POM shown above. But we'll see how much more we can do with just that simple POM above!
 
-* How do I compile my test sources?
+* How do I compile my test sources and run my unit tests?
+
+ So you can now compile your applications sources and now you've got some unit tests that you want to compile
+ and execute because every programmer always writes and executes their unit tests (nudge nudge wink wink).
+
+ Execute the following command:
+
++----+
+
+m2 test
+
++----+
+
+ Upon executing this command you should see output like the following:
+
++----+
+
+[INFO] ----------------------------------------------------------------------------
+[INFO] Building Maven Quick Start Archetype
+[INFO]    task-segment: [test]
+[INFO] ----------------------------------------------------------------------------
+[INFO] [resources:resources]
+[INFO] [compiler:compile]
+Compiling 1 source file to /home/jvanzyl/js/org.apache.maven/components/trunk/maven-site/my-app/target/classes
+[INFO] [resources:testResources]
+[INFO] [compiler:testCompile]
+Compiling 1 source file to /home/jvanzyl/js/org.apache.maven/components/trunk/maven-site/my-app/target/test-classes
+[INFO] [surefire:test]
+[INFO] Setting reports dir: /home/jvanzyl/js/org.apache.maven/components/trunk/maven-site/my-app/target/surefire-reports
+
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+[surefire] Running com.mycompany.app.AppTest
+[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.005 sec
+
+Results :
+[surefire] Tests run: 1, Failures: 0, Errors: 0
+
+[INFO] ----------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ----------------------------------------------------------------------------
+[INFO] Total time: 2 seconds
+[INFO] Finished at: Mon Oct 03 15:06:22 GMT-05:00 2005
+[INFO] Final Memory: 2M/6M
+[INFO] ----------------------------------------------------------------------------
+
++----+
+
+ If you simply want to compile your test sources you can execute the following which does not run your unit tests:
 
 +----+
 
@@ -215,10 +280,10 @@ m2 test-compile
 
 +----+
 
- Upon executing this command you should see output like the following:
+ Now that you can compile your application sources and compile your tests and execute them you'll want to move
+ on to the next logical step so you'll be asking ...
 
-
+* How do I create a JAR and install it in my local repository?
-~~* How do I create a JAR?
 
 +----+
 +----+
@@ -235,6 +300,8 @@ m2 test-compile
 FYI - In beta-2, while the other technique is still supported, the
 recommended way is finally settled:
 
+chatting with emm in irc and src/main/filters seems like a good place for filter files.
+
 <build>
   <filters>
     <filtersFile>...</filtersFile>