jvanzyl 2002/07/17 09:50:59
Added: xdocs naming-conventions.xml
Log:
o Start a naming conventions document to address the concerns of users
having problems figuring out what to name things. Long overdue, sorry.
Revision Changes Path
1.1 jakarta-turbine-maven/xdocs/naming-conventions.xml
Index: naming-conventions.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
<title>Maven Naming Conventions</title>
</properties>
<body>
<section name="Maven Naming Conventions">
<p>
This document outlines the naming conventions used in the Maven
project object model (POM). This document is an attempt to try and
unify the many various ways projects name the artifacts that they
publish for general consumption by the Java developer community.
</p>
</section>
<section name="Rules and Guidelines">
<subsection name="Projects">
<p>
A project must have a unique identifier that is comprised of
lowercase letters [a-z] where hyphens can be used. The unique id
must also start with a lowercase letter [a-z]:
</p>
<source>
<![CDATA[
<project>
<id>foo</id>
...
</project>
]]>
</source>
<p>
All references from one project to another are to be made in terms of the
unique project id. At the moment the only place in the POM where
this is relevant is the declaration of project dependencies which is
discussed below.
</p>
<p>
A project should have a human readable name that can be used in
documentation.
</p>
<source>
<![CDATA[
<project>
<id>foo</id>
<name>The Grand Master Foo</name>
...
</project>
]]>
</source>
<p>
All artifacts published by a project should be based on the
project's unique identifier.
</p>
</subsection>
<subsection name="Depenendencies">
<p>
An example of an ideal, the hopefully typical, dependency declaration
looks like the
following:
</p>
<source>
<![CDATA[
<project>
<id>bar</id>
<name>Baradelic Groove Machine</name>
...
<dependencies>
<dependency>
<id>foo</id>
<version>1.0</version>
</dependency>
</dependencies>
</project>
]]>
</source>
<p>
So, the project <code>bar</code> which depends on version
<code>1.0</code> of project <code>foo</code>. This dependency
resolves to a JAR file that is stored in the local repository.
The above entry assumes that the published JAR's name is based
on the project id. So for the above dependency entry Maven will
assume a JAR name of <code>foo-1.0.jar</code>.
</p>
<p>
As user's have noticed, this ideal situation doesn't work in all
cases for all projects. There are several situations that have to
be accounted for which require modifications of the ideal dependency
declaration:
</p>
<p>
<ul>
<li>The project id is not used as the base name of the JAR</li>
<li>The JAR name has no version declaration</li>
</ul>
</p>
</subsection>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
