Author: tchemit Date: 2009-09-02 14:53:59 +0200 (Wed, 02 Sep 2009) New Revision: 640 Added: trunk/src/site/en/ trunk/src/site/en/apt/ trunk/src/site/en/apt/MavenProjectBestPratices.apt trunk/src/site/en/apt/Todo.apt trunk/src/site/en/apt/index.apt trunk/src/site/site_en.xml Modified: trunk/pom.xml trunk/src/site/apt/MavenProjectBestPratices.apt trunk/src/site/apt/index.apt trunk/src/site/site.xml Log: [FEATURE] #37 finish documentation (french and english) Modified: trunk/pom.xml =================================================================== --- trunk/pom.xml 2009-09-01 10:39:35 UTC (rev 639) +++ trunk/pom.xml 2009-09-02 12:53:59 UTC (rev 640) @@ -206,7 +206,7 @@ <maven.test.gen.dir>${project.build.directory}/generated-test-sources</maven.test.gen.dir> <!-- locales for the site generation, by default only french --> - <maven.site.locales>fr</maven.site.locales> + <maven.site.locales>fr,en</maven.site.locales> <!-- le fichier de license du projet --> <maven.license.file>${project.basedir}/LICENSE.txt</maven.license.file> @@ -885,77 +885,6 @@ <exec.classpathScope>runtime</exec.classpathScope> </properties> </profile> - - <!-- use this plugin to run the main class --> - <profile> - <id>runJava</id> - <activation> - <activeByDefault>false</activeByDefault> - </activation> - <build> - <defaultGoal>compile</defaultGoal> - <plugins> - <plugin> - <artifactId>maven-enforcer-plugin</artifactId> - <executions> - <execution> - <id>run</id> - <goals> - <goal>enforce</goal> - </goals> - <phase>initialize</phase> - <configuration> - <rules> - <requireProperty> - <property>maven.jar.main.class</property> - <message>Could not find the "maven.jar.main.class" required property, use - -Dmaven.jar.main.class=your.main.class.fqn - </message> - </requireProperty> - </rules> - <ignoreCache>true</ignoreCache> - <failFast>true</failFast> - <fail>true</fail> - - </configuration> - </execution> - </executions> - </plugin> - - <plugin> - <artifactId>maven-dependency-plugin</artifactId> - <executions> - <execution> - <id>copy-dependencies</id> - </execution> - </executions> - </plugin> - - <plugin> - <groupId>org.codehaus.mojo</groupId> - <artifactId>exec-maven-plugin</artifactId> - <executions> - <execution> - <id>run</id> - <goals> - <goal>java</goal> - </goals> - <phase>compile</phase> - <configuration> - <mainClass>${maven.jar.main.class}</mainClass> - <classpathScope>runtime</classpathScope> - </configuration> - </execution> - </executions> - </plugin> - - </plugins> - </build> - <properties> - <exec.mainClass>${maven.jar.main.class}</exec.mainClass> - <exec.classpathScope>runtime</exec.classpathScope> - </properties> - </profile> <!-- ce profile est dedie uniquement a mavenpom pour faire des releases pour corriger les url de deployements qui marcheront pour tous les Modified: trunk/src/site/apt/MavenProjectBestPratices.apt =================================================================== --- trunk/src/site/apt/MavenProjectBestPratices.apt 2009-09-01 10:39:35 UTC (rev 639) +++ trunk/src/site/apt/MavenProjectBestPratices.apt 2009-09-02 12:53:59 UTC (rev 640) @@ -5,9 +5,9 @@ 2009-08-22 ---- -Présentation +Abstract - Ce document énumère les bonnes pratiques à retenir sur l'utilisation de maven 2. + This document enumrates best pratices to use in a maven 2 project. Préconisations générales Modified: trunk/src/site/apt/index.apt =================================================================== --- trunk/src/site/apt/index.apt 2009-09-01 10:39:35 UTC (rev 639) +++ trunk/src/site/apt/index.apt 2009-09-02 12:53:59 UTC (rev 640) @@ -7,58 +7,115 @@ Présentation - Super pom de tous nos projets. + Super pom de tous les projets {{{http://www.nuiton.org}nuiton}} et + {{{http://www.chorem.org}chorem}}. Les propriétés définies - * <<platform>> : redmine platform <nuiton.org> or <chorem.org> +* platform - * <<projectId>> : the redmine project's id (by default project.artifactId) + La palteforme redmine utilisée : <<nuiton.org>> ou <<chorem.org>> - Note : On a multi-module, must be overriden but never with project.artifactId! +* projectId - * <listId> : the prefix of all lists (by default projectId) + L'identifiant du projet redmine associé (par défaut <<project.artifactId>>) - * <repository.home.url> : the maven repository + <Note :> Sur un multi-module, la propriété doit être surchargé, sinon on + se retrouve avec des valeurs héritiés sur les modules fils, ce qui n'est pas + correct. - * <license.licenseName> : the license to use (by default lgpl_v3) +* listId - * <maven.compile.source> : the source + Le préfixe utilisé pour les listes de diffusion. (par défaut <<projectId>>). - * <maven.compile.target> : the target +* repository.home.url - * <maven.compile.encoding> : encoding to use everywhere + L'url de dépôt maven de nuiton - * <maven.src.dir> : sources dir (by default src) +* license.licenseName - * <maven.gen.dir> : where to generate (by default target/generated-sources) + La license utilisée par le projet (par défaut <<lgpl_v3>>) - * <maven.test.gen.dir> : where to generate tests (by default target/generate-test-sources) + <Note :> Pour connaitre les différentes licenses compatible, voir + {{{http://maven-site.nuiton.org/maven-helper-plugin}maven-helper-plugin}}. - * <maven.site.locales> : locales used in site generation (by default fr) +* maven.compile.source - * <maven.license.file> : path to license file (by default ${project.basedir}/LICENSE.txt) + Le niveau de java utilisé dans les sources (par défaut <<1.6>>) - * <maven.test.testFailureIgnore> : to skip tests if they fail (bu default false) +* maven.compile.target - * <maven.test.skip> : to skip test (by default false) + Le niveau de java utilisé dans le code compilé (par défaut <<1.6>>) - * <maven.reports.generate> : to skip site reports generation (by default false) +* maven.compile.encoding - * <helper.version> : the maven-helper-plugin version to use + Encoding à utiliser dans les sources (par défaut <<UTF-8>>) - <Expliquer à quoi servent ces propriétés.> +* project.reporting.outputEncoding + Encoding à utiliser dans le site (par défaut <<UTF-8>>) + +* maven.src.dir + + Répertoire des sources (par défaut <<${project.basedir}/src>>) + +* maven.gen.dir + + Répertoire de génération (par défaut <<${project.basedir}/target/generated-sources>>) + +* maven.test.gen.dir + + Répertoire de génération de tests (par défaut <<${project.basedir}/generate-test-sources>>) + +* maven.site.locales + + Locales utilisées pour la génération des sites (par défaut <<fr,en>>) + +* maven.license.file + + Chemin vers la license utilisée dans le projet (par défaut + <<${project.basedir}/LICENSE.txt>>) + +* maven.test.testFailureIgnore + + Un drapeau pour continuer même si les tests ont échoués (par défault <<false>>) + +* maven.test.skip + + Pour ne pas lancer les tests (par défaut <<false>>) + +* maven.reports.generate + + Pour ne pas lancer la génération des rapport lors de la création du site + (par défaut <<false>>) + +* maven.version + + La version de l'api de maven utilisée (principalement dans les plugins maven) + +* helper.version + + La version de {{{http://maven-site.nuiton.org/maven-helper-plugin}maven-helper-plugin}} utilisée + +* jrst.version + + La version de {{{http://maven-site.nuiton.org/jrst}jrst}} utilisée lors de la + génération du site si on utilise jrst. + + <Note:> Il ne faut pas utiliser <<jrst>> sur les librairies utilisées pour + construire <<jrst>> lui-même afin de ne pas avoir de ne pas introduire de + dépendances cycliques. + Vérification de conformité On effectue sur le pom des contrôles de conformités via - <maven-enforcer-plugin>. + {{{http://maven-site.nuiton.org/maven-helper-plugin}maven-helper-plugin}}. -propriétés obligatoires +* propriétés obligatoires aucune a l'heure actuelle -Fichiers obligatoires +* Fichiers obligatoires * README.txt @@ -66,18 +123,69 @@ * LICENSE.txt + <Note :> sur un projet multi-module, le <changelog.txt> est uniquement + obligatoire sur le pom parent, mais pas sur les modules. -Les plugins configurés +Les profiles disponibles - <<A faire>> + On a ajouté quelques profiles pour aider le développeur : +* profile <<notests>> -Montée en version d'un plugin + Ce profile permet de ne pas lancer les tests. - <<A faire>> +-------------------------------------------------------------------------------- +mvn install -Pnotests +-------------------------------------------------------------------------------- +* profile <<noreports>> -La gestion scm + Ce profile permet de ne pas lancer la génération des rapports sur le cycle <site>. +-------------------------------------------------------------------------------- +mvn site -Pnoreports +-------------------------------------------------------------------------------- + +* profile <<release-profile>> + + Ce profile (défini par maven) est utilisé lors d'un <mvn release:perform>. + On y indique qu'il faut toujours inclure les sources et la javadoc. + + Ce profile est utilisable en activant la propriété <performRelease> : + +-------------------------------------------------------------------------------- +mvn deploy -Prelease-profile +-------------------------------------------------------------------------------- + + ou + +-------------------------------------------------------------------------------- +mvn deploy -DperformRelease +-------------------------------------------------------------------------------- + + A noter que lors d'un deploy (par exemple d'une snapshot), on <<doit>> + l'utiliser afin que les utilisateurs puissent récupérer les sources et la + javadoc dans leur IDE favori. + +* profile <<run>> + + Ce profile permet de lancer une classe java depuis maven. Il faut définir une + propriété <maven.jar.main.class> qui exprime le nom qualifié de la classe à + lancer. + +-------------------------------------------------------------------------------- +mvn -Prun -Dmaven.jar.main.class=org.nuiton.MyMainClass +-------------------------------------------------------------------------------- + +* profile <<internal>> + + Ce profile permet de corriger l'url de deployement du site de <mavenpom> + et il <<DOIT>> être toujours utilisé lors d'un <mvn release:perform> de cette manière : + +-------------------------------------------------------------------------------- +mvn release:perform -DreleaseProfiles=internal +-------------------------------------------------------------------------------- + +Configuration des plugins + <<A faire>> - Added: trunk/src/site/en/apt/MavenProjectBestPratices.apt =================================================================== --- trunk/src/site/en/apt/MavenProjectBestPratices.apt (rev 0) +++ trunk/src/site/en/apt/MavenProjectBestPratices.apt 2009-09-02 12:53:59 UTC (rev 640) @@ -0,0 +1,48 @@ +---- +Maven 2 best pratices +---- +---- +2009-08-22 +---- + +Présentation + + Ce document énumère les bonnes pratiques à retenir sur l'utilisation de maven 2. + +Préconisations générales + + Inspiration du {{{http://www.javaworld.com/javaworld/jw-05-2006/jw-0529-maven.html} document}}. + + {{{http://www.javaworld.com/javaworld/jw-05-2006/images/jw-0529-maven1.gif} description}}. + + * toujours respecter la même organisation dans nos pom + + * les principales sections d'un pom : + + * POM Relationships + + * Project Information + + * Build Settings + + * Build Environment + + * Maven Environment + + A faire + +Création d'un nouveau projet lutin + + A faire + +Création d'un nouveau projet lutin multi-modules + + A faire + +Création d'un nouveau plugin lutin + + A faire + +Les plugins utilisés + + A faire Added: trunk/src/site/en/apt/Todo.apt =================================================================== --- trunk/src/site/en/apt/Todo.apt (rev 0) +++ trunk/src/site/en/apt/Todo.apt 2009-09-02 12:53:59 UTC (rev 640) @@ -0,0 +1,17 @@ +---- +TODO +---- +---- +2009-08-22 +---- + + +Création d'archetypes + + Il nous faudrait 2 archetypes pour la construction d'un nouveau projet : + + * un pour un projet no multi-modules + + * un pour les projets multi-modules + + \ No newline at end of file Added: trunk/src/site/en/apt/index.apt =================================================================== --- trunk/src/site/en/apt/index.apt (rev 0) +++ trunk/src/site/en/apt/index.apt 2009-09-02 12:53:59 UTC (rev 640) @@ -0,0 +1,188 @@ +------ +Maven nuiton pom +------ +------ +2009-09-01 +------ + +Abstract + + Parent pom of all {{{http://www.nuiton.org}nuiton}} and + {{{http://www.chorem.org}chorem}} projects. + +Defined properties + +* platform + + Redmine's platform <<nuiton.org>> or <<chorem.org>> + +* projectId + + The redmine project's id (by default <<project.artifactId>>) + + <Note :> On a multi-module, must be overriden, otherwise there is some + problem with inheritance. + +* listId + + The prefix of all lists (by default <<projectId>>) + +* repository.home.url + + The maven repository url + +* license.licenseName + + The license to use (by default <<lgpl_v3>>) + + <Note :> To know all available licenses, see + {{{http://maven-site.nuiton.org/maven-helper-plugin}maven-helper-plugin}}. + +* maven.compile.source + + The java's level of source files (by default <<1.6>>) + +* maven.compile.target + + The java's level of compiled files (by default <<1.6>>) + +* maven.compile.encoding + + Encoding to use in sources (by default <<UTF-8>>) + +* project.reporting.outputEncoding + + Encoding to use for site generation (by default <<UTF-8>>) + +* maven.src.dir + + Sources directory (by default <<${project.basedir}/src>>) + +* maven.gen.dir + + Generation directory (by default <<${project.basedir}/target/generated-sources>>) + +* maven.test.gen.dir + + Where to generate stuff for tests (by default <<${project.basedir}/target/generate-test-sources>>) + +* maven.site.locales + + Locales used in site generation (by default <<fr,en>>) + +* maven.license.file + + Path to license file (by default <<${project.basedir}/LICENSE.txt>>) + +* maven.test.testFailureIgnore + + To skip tests if they fail (by default <<false>>) + +* maven.test.skip + + To skip test (by default <<false>>) + +* maven.reports.generate + + To skip site reports generation (by default <<false>>) + +* maven.version + + The maven api version to use (in plugin mostly) + +* helper.version + + The {{{http://maven-site.nuiton.org/maven-helper-plugin}maven-helper-plugin}} + version to use. + +* jrst.version + + The {{{http://maven-site.nuiton.org/jrst}jrst}} version to use. + + <Note:> You <<SHOULD>> not use <<jrst>> for all libraries used to build <<jrst>> + himself, otherwise, you will introduce some cyclic dependencies, and we do not + want that... + +Conformity checks + + Some conformity checks are done to make sure we have all necessary files. + +* mandatory properties + + None actually + +* mandatories files + + * <README.txt> a simple file to explain how to build project + + * <changelog.txt> a file to explain modifications done between versions + + * <LICENSE.txt> the license of the project. + + <Note :> On a multi-module project, the <changelog.txt> is only required on the + parent pom but not in the child modules. + + +Available profiles + + some profiles has been added to help developper life. + +* profile <<notests>> + + Permits to skip tests. + +-------------------------------------------------------------------------------- +mvn install -Pnotests +-------------------------------------------------------------------------------- + +* profile <<noreports>> + + Skip reports generation in a <site> cycle. + +-------------------------------------------------------------------------------- +mvn site -Pnoreports +-------------------------------------------------------------------------------- + +* profile <<release-profile>> + + This profile (defined par maven) is used while a <mvn release:perform>. + We tells here to attach sources and javadoc on project deployement. + + This profile is activable via the property <performRelease> : + +-------------------------------------------------------------------------------- +mvn deploy -Prelease-profile +-------------------------------------------------------------------------------- + + or + +-------------------------------------------------------------------------------- +mvn deploy -DperformRelease +-------------------------------------------------------------------------------- + + <Note :> While doing a <deploy> (for example of a snapshot), you <<SHOULD>> + use this profile to allow users to see the sources and javadocs in their + favorite IDE. + +* profile <<run>> + + The profile permits to laucnh a java main class from maven. You have to define + a property <maven.jar.main.class> which give the fully qualified name of the + class. + +-------------------------------------------------------------------------------- +mvn -Prun -Dmaven.jar.main.class=org.nuiton.MyMainClass +-------------------------------------------------------------------------------- + +* profile <<internal>> + + This profile permits to fix the site url of the <mavenpom> project. + It <<MUST>> be used when doing a release of <mavenpom> : + +-------------------------------------------------------------------------------- +mvn release:perform -DreleaseProfiles=internal +-------------------------------------------------------------------------------- + +Configuration of plugins + + <<To be done>> Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-01 10:39:35 UTC (rev 639) +++ trunk/src/site/site.xml 2009-09-02 12:53:59 UTC (rev 640) @@ -29,8 +29,6 @@ </links> <breadcrumbs> - <!-- can not be use, since this is a static content --> - <!--<item name="${platformName}" href="http://www.${platform}" />--> <item name="${project.name}" href="${project.url}" /> </breadcrumbs> @@ -43,7 +41,7 @@ <item name="A faire" href="Todo.html"/> </menu> - <menu name="Links"> + <menu name="Liens"> <item name="maven-nuiton-skin" href="../maven-nuiton-skin"/> <item name="maven-helper-plugin" href="../maven-helper-plugin"/> </menu> Added: trunk/src/site/site_en.xml =================================================================== --- trunk/src/site/site_en.xml (rev 0) +++ trunk/src/site/site_en.xml 2009-09-02 12:53:59 UTC (rev 640) @@ -0,0 +1,52 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project name="${project.name}"> + + <publishDate format="yyyy-MM-dd"/> + + <skin> + <groupId>org.nuiton</groupId> + <artifactId>maven-nuiton-skin</artifactId> + <version>1.0.0</version> + </skin> + + <bannerLeft> + <name>${project.name}</name> + <href>index.html</href> + </bannerLeft> + + <bannerRight> + <src>http://www.codelutin.com/images/lutinorange-codelutin.png</src> + <href>${project.organization.url}</href> + </bannerRight> + + <body> + <links> + <item name="Chorem" href="http://www.chorem.org"/> + <item name="Nuiton" href="http://www.nuiton.org"/> + <item name="Labs" href="http://labs.libre-entreprise.org/"/> + <item name="${project.organization.name}" href="${project.organization.url}"/> + <item name="maven nuiton repository" href="${repository.home.url}"/> + </links> + + <breadcrumbs> + <item name="${project.name}" href="${project.url}" /> + </breadcrumbs> + + <menu name="User"> + <item name="Home" href="index.html"/> + </menu> + + <menu name="Dev"> + <item name="Maven best pratices" href="MavenProjectBestPratices.html"/> + <item name="Todo" href="Todo.html"/> + </menu> + + <menu name="Links"> + <item name="maven-nuiton-skin" href="../maven-nuiton-skin"/> + <item name="maven-helper-plugin" href="../maven-helper-plugin"/> + </menu> + + <menu ref="reports"/> + + </body> +</project>