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