/Prototipo/Servlet/lib/xstream-distribution-1.4.1-bin/xstream-1.4.1/docs/versioning.html
HTML | 199 lines | 158 code | 29 blank | 12 comment | 0 complexity | 2035d9ce187c60f2c59681e6aa0213e8 MD5 | raw file
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 2<html xmlns="http://www.w3.org/1999/xhtml"> 3<!-- 4 Copyright (C) 2005, 2006 Joe Walnes. 5 Copyright (C) 2006, 2007, 2008 XStream committers. 6 All rights reserved. 7 8 The software in this package is published under the terms of the BSD 9 style license a copy of which has been included with this distribution in 10 the LICENSE.txt file. 11 12 Created on 29. January 2005 by Joe Walnes 13 --> 14 <head> 15 <title>XStream - About Versioning</title> 16 <link rel="stylesheet" type="text/css" href="style.css"/> 17 18 19 20 21 <!-- Google analytics --> 22 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> 23 </script> 24 <script type="text/javascript"> 25 _uacct = "UA-110973-2"; 26 urchinTracker(); 27 </script> 28 29 </head> 30 <body> 31 32 <div id="banner"> 33 <a href="index.html"><img id="logo" src="logo.gif" alt="XStream"/></a> 34 </div> 35 36 <div id="center" class="Content2Column"> <!-- Content3Column for index --> 37 <div id="content"> 38 <h1 class="FirstChild">About Versioning</h1> 39 40 41 42 <p>The XStream project follows strict rules that govern its use of version 43 numbers. The version number of a release indicates how that release 44 is compatible with previous and future releases.</p> 45 46 <p>Version numbers have the form 47 <var>major</var>.<var>minor</var>.<var>patch</var>. A major 48 version identifies the product stage of the project. Two libraries with 49 different major version are designed to work together in the same 50 application. This implies a major change in the API - either by not 51 sharing the same types or using a different package name.</p> 52 53 <p>The minor version number identifies the API version. A release that 54 changes the API in a way that breaks backwards compatibility will increment 55 the minor version number and reset the patch version to zero. The patch 56 version number identifies the backwards compatible revision of the API. A 57 change in the minor version will still be mostly backward compatible, but 58 may need some compatibility settings or slight migration adjustments. The 59 patch version number identifies revisions that do not change the API 60 although new API elements may occur or existing API may be deprecated to 61 prepare users for the next release with a change in the minor version. A 62 release that fixes bugs or refactors implementation details without changing 63 the API will have the same minor and major versions as the previous release 64 and increment the patch number.</p> 65 66 <p>A hypothetical example:</p> 67 <table summary="Hypothetical examples for version numbering"> 68 <tr><td>1.0.0</td><td>First release</td></tr> 69 <tr><td>1.0.1</td><td>Improves Javadoc comments, fixes bug</td></tr> 70 <tr><td>1.1.0</td><td>Adds new API elements, may cause some migration</td></tr> 71 <tr><td>1.1.1</td><td>Adds new API elements, deprecates some API elements</td></tr> 72 <tr><td>1.1.2</td><td>Fixes bugs</td></tr> 73 <tr><td>1.2.0</td><td>Adds new API, needs some migration effort and removes deprecated elements</td></tr> 74 <tr><td>2.0.0</td><td>Complete API redesign, can be used simultanly with 1.x series.</td></tr> 75 <tr><td>2.0.1</td><td>Deprecates API, fixes bugs</td></tr> 76 <tr><td>2.1.0</td><td>Adds new API elements</td></tr> 77 <tr><td>etc.</td><td>etc.</td></tr> 78 </table> 79 80 <h2 id="rc">Release Candidates</h2> 81 82 <p>Before a new major or minor release, XStream will make release 83 candidate (RC) packages available so that users can test them against 84 their own code. There will be one or more release candidates given the 85 version <var>major</var>.<var>minor</var>.0 RC<var>n</var>, where the 86 major and minor version numbers identify the upcoming release and RC1 87 identifies the first candidate release, RC2 the second, and so on.</p> 88 89 <p>A release candidate does not guarantee backward compatibility with 90 new API features introduced by any previous RC of the same upcoming 91 version. 92 A major version RC can change/remove API features introduced in a 93 previous RC for the same major version; a minor version RC can change 94 API features introduced by any previous RC of the same upcoming minor 95 version but guarantees backward compatibility with the previous minor 96 version.</p> 97 98 <h2 id="snapshots">Development Snapshots</h2> 99 100 <p>During development, the the developers may publish snapshot packages 101 from time to time. These are not guaranteed to be complete: 102 Although the unit tests will all pass the snapshot will probably contain 103 failing acceptance tests that describe planned or requested features that 104 have not yet been implemented. Snapshots are identified by the UTC time 105 at which the package was built. The timestamp has the form 106 <var>VERSION-YYYYMMDD.hhmmss-n</var>, where VERSION is the upcoming 107 version, YYYY is the (four-digit) year, MM the month, DD the day, hh the 108 hour, mm the minute, ss the second and n a sequential number.</p> 109 110 <h2 id="internal">Internal Classes</h2> 111 112 <p>Many classes are for internal use only and not designed to be used by 113 end users. These are exempt from the versioning rules above.</p> 114 115 <p>Such classes are clearly marked as internal in the source code 116 headers and are excluded from the published JavaDoc.</p> 117 118 <h2 id="versioning">Versioning and Deprecation</h2> 119 120 <p>A patch release might deprecate some API features. Deprecated features 121 will not actually be removed until the next minor release. 122 A release will never remove API features that have not been deprecated in 123 a previous release. 124 </p> 125 126 127 128 <br/> 129 130 </div> 131 </div> 132 133 <div class="SidePanel" id="left"> 134 <div class="MenuGroup"> 135 <h1>Software</h1> 136 <ul> 137 <li><a href="index.html">About XStream</a></li> 138 <li><a href="news.html">News</a></li> 139 <li><a href="changes.html">Change History</a></li> 140 <li class="currentLink">About Versioning</li> 141 </ul> 142 </div> 143 <div class="MenuGroup"> 144 <h1>Evaluating XStream</h1> 145 <ul> 146 <li><a href="tutorial.html">Two Minute Tutorial</a></li> 147 <li><a href="graphs.html">Object references</a></li> 148 <li><a href="manual-tweaking-output.html">Tweaking the Output</a></li> 149 <li><a href="license.html">License</a></li> 150 <li><a href="download.html">Download</a></li> 151 <li><a href="references.html">References</a></li> 152 <li><a href="parser-benchmarks.html">Parser Benchmarks</a></li> 153 <li><a href="http://www.ohloh.net/projects/3459">Code Statistics</a></li> 154 </ul> 155 </div> 156 <div class="MenuGroup"> 157 <h1>Using XStream</h1> 158 <ul> 159 <li><a href="architecture.html">Architecture Overview</a></li> 160 <li><a href="converters.html">Converters</a></li> 161 <li><a href="faq.html">Frequently Asked Questions</a></li> 162 <li><a href="list-user.html">Users' Mailing List</a></li> 163 <li><a href="issues.html">Reporting Issues</a></li> 164 </ul> 165 </div> 166 <div class="MenuGroup"> 167 <h1>Javadoc</h1> 168 <ul> 169 <li><a href="javadoc/index.html">XStream Core</a></li> 170 <li><a href="hibernate-javadoc/index.html">Hibernate Extensions</a></li> 171 <li><a href="benchmark-javadoc/index.html">Benchmark Module</a></li> 172 </ul> 173 </div> 174 <div class="MenuGroup"> 175 <h1>Tutorials</h1> 176 <ul> 177 <li><a href="tutorial.html">Two Minute Tutorial</a></li> 178 <li><a href="alias-tutorial.html">Alias Tutorial</a></li> 179 <li><a href="annotations-tutorial.html">Annotations Tutorial</a></li> 180 <li><a href="converter-tutorial.html">Converter Tutorial</a></li> 181 <li><a href="objectstream.html">Object Streams Tutorial</a></li> 182 <li><a href="persistence-tutorial.html">Persistence API Tutorial</a></li> 183 <li><a href="json-tutorial.html">JSON Tutorial</a></li> 184 </ul> 185 </div> 186 <div class="MenuGroup"> 187 <h1>Developing XStream</h1> 188 <ul> 189 <li><a href="how-to-contribute.html">How to Contribute</a></li> 190 <li><a href="list-dev.html">Developers' Mailing List</a></li> 191 <li><a href="team.html">Development Team</a></li> 192 <li><a href="repository.html">Source Repository</a></li> 193 <li><a href="http://bamboo.ci.codehaus.org/browse/XSTREAM">Continuous Integration</a></li> 194 </ul> 195 </div> 196 </div> 197 198 </body> 199</html>