update and improve doc on cache and change management

git-svn-id: https://svn.apache.org/repos/asf/incubator/ivy/core/trunk@597169 13f79535-47bb-0310-9956-ffa450edef68

doc/concept.html

@@ -230,7 +230,23 @@ Prior to Ivy 1.4 circular dependencies where causing a failure in Ivy. As of Ivy
 </ul>
 
 See the <a href="configuration/conf.html">configuration page</a> to see how to configure the circular dependency strategy you want to use.
-	</textarea>
+
+<h1><a name="change">Cache and Change Management</a></h1>
+Ivy heavily relies on a local cache to avoid accessing remote repositories too often, thus saving a low of network bandwidth and time. To optimize the dependency resolution and the way the cache is used, Ivy assumes by default that a revision never changes. So once Ivy has a module in its cache (metadata and artifacts), it trusts the cache and do not even query the repository. This optimization is very useful in most cases, and causes no problem as long as you respect this paradigm: a revision never changes. Besides performance, there are several [[bestpractices good reasons]] to follow this principle.	
+
+However, depending on your current build system and your dependency management strategy, you may prefer to update sometimes your modules. There are two kind of changes to consider:
+<h3>change in module metadata</h3>
+Since pretty often module metadata are not considered by module providers with as much attention as their API or behavior (if they even provide module metadata), it happens more than we would like that we have to update module metadata: a dependency has been forgotten, or another one is missing, ...
+
+In this case, setting checkModified="true" on your dependency resolver will be the solution. This flag tells to Ivy to check if module metadata has been modified compared to the cache. Ivy first checks the metadata last modified timestamp on the repository to download it only if necessary, and then update it when needed.
+<h3>Changes in artifacts</h3>
+Some people, especially those coming from maven 2 land, like to use one special revision to handle often updated modules. In maven 2 this is called a SNAPSHOT version, and some argue that it helps saves disk space to keep only one version for the high number of intermediary builds you can make whilst developing.
+
+Ivy supports this kind of approach with the notion of changing revision. A changing revision is just that: a revision for which Ivy should consider that the artifacts may change over time. To handle this, you can either specify a dependency as changing on the [[ivyfile/dependency]] tag, or use the changingPattern and changingMatcher attributes on your [[configuration/resolvers]] to indicate which revision or group of revisions should be considered as changing.
+
+Once Ivy knows that a revision is changing, it will follow this principle to avoid checking your repository too often: if the module metadata has not changed, it will considered the whole module (including artifacts) as not changed. Even if the module descriptor file has changed, it will check the publication data of the module to see if this is a new publication of the same revision or not. Then if the publication date has changed, it will check the artifacts last modified timestamps, and download them accordingly.
+
+So if you want to use changing revisions, use the [[ant:publish]] task to publish your modules, it will take care of updating the publication date, and everything will work fine. And remember to set checkModified=true" on your resolver too!</textarea>
 <script type="text/javascript">xooki.postProcess();</script>
 </body>
 </html>

doc/configuration/resolvers.html

@@ -95,12 +95,12 @@ All resolvers of the same type share some common attributes detailed here:
         <td>No</td>
         <td>Yes</td>
     </tr>
-    <tr><td>changingPattern</td><td>Indicates for which revision pattern this resolver should check lastmodified date to know if an artifact file is up to date. <span class="since">since 1.4</span></td>
+    <tr><td>changingPattern</td><td>Indicates for which revision pattern this resolver should check lastmodified date to know if an artifact file is up to date. <span class="since">since 1.4</span>. See <a href="../concept.html#change">cache and change management</a> for details.</td>
         <td>No, defaults to none</td>
         <td>Yes</td>
         <td>Yes</td>
     </tr>
-    <tr><td>changingMatcher</td><td>The name of the <a href="../concept.html#matcher">pattern matcher</a> to use to match a revision against the configured changingPattern. <span class="since">since 1.4</span></td>
+    <tr><td>changingMatcher</td><td>The name of the <a href="../concept.html#matcher">pattern matcher</a> to use to match a revision against the configured changingPattern. <span class="since">since 1.4</span>. See <a href="../concept.html#change">cache and change management</a> for details.</td>
         <td>No, defaults to exactOrRegexp</td>
         <td>Yes</td>
         <td>Yes</td>

doc/ivyfile/dependency.html

@@ -114,12 +114,12 @@ If you prefer more verbose mapping declaration, everything is also possible with
 
 <h2>Artifact restriction</h2>
 Moreover, the dependency element also supports an artifact restriction feature (since 0.6).
-See <a href="#dependency-artifact">dependency artifact restriction</a> for details. <br/><br/>
+See <a href="#dependency-artifact">dependency artifact restriction</a> for details.
 
 <h2>Forcing revision</h2>
 Finally, the dependency element also supports an a force attribute (since 0.8), which gives an indication
-to conflicts manager to force the revision of a dependency to the one given here.<br/>
-See <a href="../ivyfile/conflicts.html">conflicts manager</a> for details. <br/><br/>
+to conflicts manager to force the revision of a dependency to the one given here.
+See <a href="../ivyfile/conflicts.html">conflicts manager</a> for details. 
 
 <span class="since">since 1.4</span> this tag supports <a href="../concept.html#extra">extra attributes</a>
 <h1>Attributes</h1>
@@ -143,7 +143,7 @@ See <a href="../ivyfile/conflicts.html">conflicts manager</a> for details. <br/>
         <td>No, defaults to defaultconf attribute of dependencies element if neither conf attribute nor conf children element is given</td></tr>
     <tr><td>transitive</td><td>true to resolve this dependency transitively, false otherwise (<span class="since">since 1.2</span>)</td>
         <td>No, defaults to true</td></tr>
-    <tr><td>changing</td><td>true if the dependency artifacts may change without revision change, false otherwise (<span class="since">since 1.2</span>). Artifacts update will be looked after only if the publication date of the ivy file has changed. Note that this is not a recommended use and that it avoid some cache optimization in ivy.</td>
+    <tr><td>changing</td><td>true if the dependency artifacts may change without revision change, false otherwise (<span class="since">since 1.2</span>). See <a href="../concept.html#change">cache and change management</a> for details.</td>
         <td>No, defaults to false</td></tr>
 </tbody>
 </table>

doc/terminology.html

@@ -26,12 +26,6 @@
 <body>
 	<textarea id="xooki-source">
 Here are some terms used in Ivy, with their definitions in Ivy:<br/>
-<h2>Ivy file</h2>
-An ivy file is an xml file which is used to describe dependencies of a module (see below). It is usually named ivy.xml.
-<h2>Settings</h2>
-Ivy settings files are xml files used to configure ivy to indicate where the dependencies can be found and how. 
-<em>Prior to Ivy 2.0, these files were called configuration files and usually named ivyconf.xml. This resulted in a confusion between module configurations and configuration files, so they have been renamed in settings files. 
-If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only a problem of update of the doc/tutorial/article. Feel free to report any problem like this if you find such inconsistencies in this documentation.</em>
 <h2>Organisation</h2>
 An organisation is either a company or a simple group of person
 which produce software. Ivy handle only one level of organisation, so you cannot
@@ -72,6 +66,20 @@ Three statuses are defined by default in ivy:
 <li>release: revision fully tested and labelled fall in this category</li>
 </ul>
 <span class="since">since 1.4</span> This list is <a href="configuration/statuses.html">configurable</a> in your configuration file.
+<h2>Module descriptor or metadata</h2>
+A generic way to identify what describes a module: the identifier (organisation, name, branch, revision), the published artifacts and the dependencies.
+
+The most common module descriptors in Ivy are [[ivyfile]], xml files with an Ivy specific syntax, and usually called ivy.xml.
+
+But since Ivy is also compatible with maven 2 metadata format (called pom, for Project Object Model), pom files falls into the category of module descriptors.
+
+And because Ivy accepts pluggable module descriptor parsers, you can use almost whatever you want as module descriptors.
+
+<h2>Settings</h2>
+Ivy settings files are xml files used to configure ivy to indicate where the modules can be found and how. 
+<em>Prior to Ivy 2.0, these files were called configuration files and usually named ivyconf.xml. This resulted in a confusion between module configurations and configuration files, so they have been renamed in settings files. 
+If you happen to fall on an ivyconf file or something called a configuration file, most of the time it's only a problem of update of the doc/tutorial/article. Feel free to report any problem like this if you find such inconsistencies in this documentation.</em>
+
 <h2>Repository</h2>
 What is called a repository in Ivy is a location where Ivy is able to find your modules artifacts and metadata (i.e. ivy files in most cases).
 Ivy can be used with complex repositories configured very finely. You can use <a href="concept.html">Dependency Resolvers</a> to do so.