You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/03/02 14:07:36 UTC
svn commit: r155914 - in maven/maven-1/core/trunk/xdocs: faq.fml
using/bestpractices.xml using/customising.xml
Author: brett
Date: Wed Mar 2 05:07:33 2005
New Revision: 155914
URL: http://svn.apache.org/viewcvs?view=rev&rev=155914
Log:
best practices for reproducibility
Modified:
maven/maven-1/core/trunk/xdocs/faq.fml
maven/maven-1/core/trunk/xdocs/using/bestpractices.xml
maven/maven-1/core/trunk/xdocs/using/customising.xml
Modified: maven/maven-1/core/trunk/xdocs/faq.fml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/faq.fml?view=diff&r1=155913&r2=155914
==============================================================================
--- maven/maven-1/core/trunk/xdocs/faq.fml (original)
+++ maven/maven-1/core/trunk/xdocs/faq.fml Wed Mar 2 05:07:33 2005
@@ -732,7 +732,6 @@
<faq id="filtering-resources">
<question>How can I filter properties into resource files as part of the build?</question>
<answer>
-<!-- TODO: filters: add to using somewhere, and reference. Also add warning about reproducible artifacts... -->
<p>
This can be done using resource filtering. In your POM, add the filtering property to your existing
resources definition. Please refer to <a href="using/resources.html">Resources</a> for more information.
Modified: maven/maven-1/core/trunk/xdocs/using/bestpractices.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/bestpractices.xml?view=diff&r1=155913&r2=155914
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/bestpractices.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/bestpractices.xml Wed Mar 2 05:07:33 2005
@@ -34,12 +34,60 @@
<!-- TODO: more to come -->
<subsection name="Reproduciblity">
<p>
- <!-- TODO! -->
+ It is important to make sure a build is reproducible. This means a few things:
</p>
- </subsection>
- <subsection name="Properties">
+ <ol>
+ <li>That any user can check it out and build as is (or with minimal configuration)</li>
+ <li>That you can check out a historical codebase and it should build as it did then</li>
+ <li>That a generated artifact for a particular version of a project should always be built identically</li>
+ </ol>
<p>
- <!-- TODO! -->
+ Making sure any user can check it out and build means that you must avoid the need for properties specific
+ to your environment. The best practices to follow here are:
+ </p>
+ <ul>
+ <li>Minimise the number of properties in <code>$HOME/build.properties</code> and ensure they are only
+ those required for your particular environment, and that it is well known that they need to be set (eg
+ HTTP proxy settings, J2EE server installation path)</li>
+ <li>Don't use absolute paths in properties and scripts for a project</li>
+ <li>If you must add an environment specific property, add it to <code>build.properties</code> in the project,
+ but don't commit it to source control. Commit a sample properties file that other developers will know to
+ copy and edit accordingly. However, wherever possible, use sensible defaults to avoid the need for this.</li>
+ </ul>
+ <p>
+ Being able to check out a historical codebase is more important in some environments than others, but often
+ you don't know you need it until it is too late, so it is a good practice to follow.
+ </p>
+ <ul>
+ <li>Follow the property rules above as they will also cause old builds to fail as things change in a local
+ environment</li>
+ <li>Make sure that releases use known versions of dependencies - don't depend on SNAPSHOTs that are subject to
+ change and likely to be different the next time you build from when the original release way</li>
+ <li>Document the version of Maven and plugins installed when building the project. This information can be
+ obtained with <code>maven --info</code>. Future versions of Maven aim to make this easier to keep consistent
+ through the life of the project.</li>
+ </ul>
+ <p>
+ Finally, make sure generated artifacts are always built identically. This is important as two files with the
+ same name, but different settings built in can become very confusing. Also, you often do not want to have to
+ rebuild an artifact as it goes from staging to QA to production as it introduces the risk that it may be
+ built differently (especially if the previous principles were not adhered to!) Some recommendations for
+ this are:
+ </p>
+ <ul>
+ <li>Avoid the need to filter resources. While this can be useful in a development environment, it usually
+ requires rebuilding of an artifact between different phases of deployment. The best alternative is to
+ externalise the configuration - for example in J2EE (where this is a common occurrence), make sure all
+ configurable information such as database connection properties are in the deployment descriptor, provided
+ through JNDI outside of the webapp or other deployable item. This means the particular artifact can be
+ deployed identically into different servers, with just the external configuration differing.</li>
+ <li>Follow the other rules above - avoid including resources outside of the base directory of the project,
+ and don't use properties customised to a particular environment.</li>
+ </ul>
+ <p>
+ One helpful method to assist reproducibility, if your environment has the capacity, is to set up a user on a
+ machine with a clean environment that matches the target environment, with known properties, plugins and other
+ software. This user can be used to build releases from a known baseline.
</p>
</subsection>
<subsection name="Scripting">
Modified: maven/maven-1/core/trunk/xdocs/using/customising.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/customising.xml?view=diff&r1=155913&r2=155914
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/customising.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/customising.xml Wed Mar 2 05:07:33 2005
@@ -64,7 +64,7 @@
</p>
<p>
Note that while properties are essential to configuring Maven and it's plugins, they can also be a source of
- bad practices. See the <a href="bestpractices.html#Properties">Best Practices</a> guide for more information.
+ bad practices. See the <a href="bestpractices.html#Reproduciblity">Best Practices</a> guide for more information.
</p>
</subsection>
<subsection name="Scripting Maven">
@@ -92,6 +92,10 @@
<p>
The <code>project</code> element is the root element, and can specify a default goal name for the project.
The namespace definitions are used by Jelly to import tag libraries.
+ </p>
+ <p>
+ Within this file, you can define new goals, or attach hooks to existing ones, write logic using Jelly tag
+ libraries, and use existing Ant tasks to add build behaviour.
</p>
<p>
For more information on scripting in general, please see the
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org