| blob | 7044a37b77bba7ca25955f5d442af43801dbea24 |
1 Versioning Scheme
2 =================
4 Waffle's version numbering scheme follows the rules [1] set by the Apache Portable Runtime Project, which are
5 reproduced [2] below. The scheme allows multiple versions of a library and its headers to be installed in parallel.
7 [1] https://apr.apache.org/versioning.html
8 [2] Downloaded on 2012-08-19 and converted from html to text with `html2text -width 120 -style pretty -nobs`.
10 -----------------------------------------------------------------------------------------------------------------------
13 _The_Apache_Portable_Runtime_Project_
15 Get Involved
16 APR's Version Numbering
17 Subversion
18 Mailing_Lists This document covers how the APR projects are versioned. Since the APR projects
19 Snapshots are libraries, it is very important to define a stable API for users of the
20 Build_on_Win32 libraries. However, we also need to move the libraries forward, technologically.
21 Build_on_Unix To balance these two needs, a strict policy of versioning is required, which
22 users can rely upon to understand the limitations, restrictions, and the changes
23 Download! that can occur from one release of APR to the next.
25 from_a_mirror * The_Basics
26 * Source_Compatibility
27 APR Docs * Binary_Compatibility
28 * Examples
29 Version_1.4 * Strategy
30 Version_0.9 * Version_Checking
31 Trunk (dev) * Parallel_Installation
32 * Other_Notes
33 APR-util Docs
35 Version_1.4
36 Version_0.9
37 Trunk (dev) The Basics
39 APR-iconv Docs Versions are denoted using a standard triplet of integers: MAJOR.MINOR.PATCH. The
40 basic intent is that MAJOR versions are incompatible, large-scale upgrades of the
41 Version_1.2 API. MINOR versions retain source and binary compatibility with older minor
42 Version_0.9 versions, and changes in the PATCH level are perfectly compatible, forwards and
43 Trunk (dev) backwards.
44 It is important to note that a library that has not reached 1.0.0 is not subject to
45 Guidelines the guidelines described in this document. Before a 1.0 release (version 0.x.y),
46 the API can and will be changing freely, without regard to the restrictions
47 Project_Guidelines detailed below.
48 Contributing
49 Version_Numbers
51 Miscellaneous Source Compatibility
53 License We define "source compatible" to mean that an application will continue to build
54 Security_Reports without error, and that the semantics will remain unchanged.
55 Projects_using_APR Applications that write against a particular version will remain source-compatible
56 Sponsors against later versions, until the major number changes. However, if an application
57 Sponsorship uses an API which has become available in a particular minor version, it
58 (obviously) will no longer build or operate against previous minor versions.
62 Binary Compatibility
64 We define "binary compatible" to mean that a compiled application can be linked
65 (possibly dynamically) against the library and continue to function properly.
66 Similar to source compatibility, an application that has been compiled against a
67 particular version will continue to be linkable against later versions (unless the
68 major number changes). It is possible that an application will not be able to
69 successfully link against a previous minor version.
73 Examples
75 Here are some examples to demonstrate the compatibility:
77 Original Version New Version Compatible?
78 2.2.3 2.2.4 Yes
79 Compatibility across patch versions is guaranteed.
80 2.2.3 2.2.1 Yes
81 Compatibility across patch versions is guaranteed.
82 2.2.3 2.3.1 Yes
83 Compatibility with later minor versions is
84 guaranteed.
85 2.2.3 2.1.7 No
86 Compatibility with prior minor versions is not
87 guaranteed.
88 2.2.3 3.0.0 No
89 Compatibility with different major versions is not
90 guaranteed.
91 2.2.3 1.4.7 No
92 Compatibility with different major versions is not
93 guaranteed.
95 Note: while some of the cells say "no", it is possible that the versions may be
96 compatible, depending very precisely upon the particular APIs used by the
97 application.
101 Strategy
103 This section details how we will build the code to meet the above
104 requirements and guidelines.
106 Patch Version
108 To retain perfect source and binary compatibility, a patch
109 release can only change function implementations. Changes to
110 the API, to the signatures of public functions, or to the
111 interpretation of function parameters is not allowed.
112 Effectively, these releases are pure bug fix releases.
116 Minor Versions
118 Minor releases can introduce new functions, new symbolic and
119 enumerated constants, and deprecate existing functions.
122 New functions
123 An application coded against an older minor release will
124 still have all of its functions available with their
125 original signatures. Once an application begins to use a
126 new function, however, they will be unable to work
127 against older minor versions.
128 It is tempting to say that introducing new functions
129 might create incompatibility across minor releases. If
130 an application takes advantage of an API that was
131 introduced in version 2.3 of a library, then it is not
132 going to work against version 2.2. However, we have
133 stated that an any application built against version 2.2
134 will continue to work for all 2.x releases. Thus, an
135 application that states "requires 2.3 or later" is
136 perfectly acceptable -- the user or administrator simply
137 upgrades the installed library to 2.3. This is a safe
138 operation and will not break any other application that
139 was using the 2.2 library.
140 In other words, yes an incompatibility arises by
141 mandating that a specific version needs to be installed.
142 But in practice, this will not be a problem since
143 upgrading to newer versions is always safe.
145 New constants
146 Similar to functions, all of the original (old)
147 constants will be available to an application. An
148 application can then choose to use new constants to pick
149 up new semantics and features.
151 Replacing functions
152 This gets a bit trickier. The original function must
153 remain available at the link-level so that an
154 application compiled against a minor version will
155 continue to work with later minor versions. Further, if
156 an application is designed to work with an earlier minor
157 version, then we don't want to suddenly change the
158 requirements for that application. This means that the
159 headers cannot silently map an old function into a newer
160 function, as that would turn an application, say, based
161 on 1.2 into an application requiring the 1.4 or later
162 release.
163 This means that functions cannot truly be replaced. The
164 new, alternate function can be made available in the
165 header and applications can choose to use it (and become
166 dependent upon the minor release where the function
167 appears).
168 It is possible to design a set of headers where a macro
169 will always refer to the "latest" function available. Of
170 course, if an application chooses to use this macro,
171 then the resulting compiled-binary will be dependent
172 upon whatever version it was compiled against. This
173 strategy adds the new functionality for applications,
174 yet retains the necessary source and binary
175 compatibility for applications designed or built against
176 previous minor releases.
177 Constants (enumerated values and preprocessor macros)
178 are not allowed to change since an older application
179 will still be using them. Similarly, function signatures
180 at the link-level may not change, so that support for
181 older, compiled applications is maintained.
183 Deprecating functions
184 Since a function must remain available for applications
185 coded against a previous minor release, it is only
186 possible to "deprecate" a function. It cannot be removed
187 from the headers (so that source compatibility is
188 retained) and it cannot be removed from the library (so
189 that binary compatibility is retained).
190 If you deprecate a function in APR, please mark it as
191 such in the function documentation, using the doxygen
192 "\deprecated" tag. Deprecated functions can only be
193 removed in major releases.
194 A deprecated function should remain available through
195 the original header. The function prototype should
196 remain in the same header, or if moved to a "deprecated
197 functions" header, then the alternate header should be
198 included by the original header. This requirement is to
199 ensure that source compatibility is retained.
200 Finally, if you are deprecating a function so that you
201 can change the name of the function, please use the
202 method described above under "Replacing functions", so
203 that projects which use APR can retain binary
204 compatibility.
205 Note that all deprecated functions will be removed at
206 the next major version bump.
211 Major Versions
213 Any kind of change can be made during a major version
214 release. Particular types of changes that might occur:
216 * remove or change constants
217 * remove (deprecated) functions
218 * fold together macro-ized function replacements
225 Version Checking
227 In many cases, the user of a library will need to check the version that they
228 are compiling against, or that is being used at runtime. Because of the strict
229 rules of source and binary compatibility, these checks can be simpler and more
230 complicated depending on what is needed.
232 Compile-time Checks
234 Libraries should make their version number available as
235 compile-time constants. For example:
237 #define FOO_MAJOR_VERSION 1
238 #define FOO_MINOR_VERSION 4
239 #define FOO_PATCH_VERSION 0
241 The above symbols are the minimum required for this
242 specification.
243 An application that desires, at compile-time, to decide on
244 whether and how to use a particular library feature needs to
245 only check two values: the major and the minor version. Since,
246 by definition, there are no API changes across patch versions,
247 that symbol can be safely ignored. Note that any kind of a
248 check for a minimum version will then pin that application to
249 at least that version. The application's installation mechanism
250 should then ensure that that minimal version has been installed
251 (for example, using RPM dependency checks).
252 If the feature changes across minor versions are source
253 compatible, but are (say) simply different choices of values to
254 pass into the library, then an application can support a wider
255 variety of installed libraries if it avoids compile-time
256 checks.
260 Run-time Checks
262 A library meeting this specification should support a way for
263 an application to determine the library's version at run-time.
264 This will usually be emboded as a simple function which returns
265 the MAJOR, MINOR, and PATCH triplet in some form.
266 Run-time checks are preferable in all cases. This type of check
267 enables an application to run against a wider variety of minor
268 releases of a library (the application is "less coupled" to a
269 particular library release). Of course, if an application
270 requires a function that was introduced in a later, minor
271 release, then the application will require that, at least, that
272 release is installed on the target system.
273 Run-time checks are particurly important if the application is
274 trying to determine if the library has a particular bug that
275 may need to be worked around, but has been fixed in a later
276 release. If the bug is fixed in a patch release, then the only
277 avenue for an application is to perform a runtime check. This
278 is because an application cannot require a specific patch level
279 of the library to be installed -- those libraries are perfectly
280 forward and backwards compatible, and the administrator is free
281 to choose any patch release, knowing that all applications will
282 continue to function properly. If the bug was fixed in a minor
283 release, then it is possible to use a compile-time check, but
284 that would create a tighter coupling to the library.
290 Parallel Installation
292 Parallel installation refers to the ability to install multiple versions of a
293 library simultaneously -- they exist in parallel. This document will not discuss
294 the full rationale for why this is important, but will instead detail how this
295 versioning specification maps onto those concepts. Please refer to Havoc
296 Pennington's_document for futher details and the rationale behind this form of
297 parallel installation.
299 Library Naming
301 On Unix-ish platforms, the library name should include the MAJOR
302 version number:
304 libFOO-MAJOR.so
306 This strategy allows an application to explicitly state which
307 version of the library that it wants to link against. If the
308 application was built for version 2 of the API, then it can link
309 against libFOO-2.so. If another application was built against
310 version 3 of the API, then it links against libFOO-3.so. Since both
311 libraries can reside on the system at the same time, both
312 applications' needs can be satisfied.
313 Typically, shared libraries on Unix-ish platforms will set up
314 symlinks from the .so library to specific versions of that library.
315 For example:
317 libFOO-MAJOR.so -> libFOO-MAJOR.so.0
318 libFOO-MAJOR.so.0 -> libFOO-MAJOR.so.0.MINOR.PATCH
320 In this configuration, applications will be bound to the .so.0
321 library. The minor version does not come into play here because we
322 want applications to dynamically load and link to the new library
323 when a new minor version is installed. Thus, the MINOR and the
324 PATCH values are relegated to the library name after the .so.0
325 portion.
326 The implication here is that build systems for libraries should
327 arrange to generate .so libraries matching the above pattern.
331 Include Directories
333 The default installation directory for a library's include files
334 should specify the MAJOR version number, and should normally be
335 installed as a subdirectory in some standard location. For example:
337 /usr/include/FOO-MAJOR/
339 An application can place the FOO-MAJOR directory on its include
340 path and include the files normally:
342 #include <FOO-stuff.h>
343 #include <FOO-more.h>
345 Depending upon the API that the application is designed to work
346 against, it can simply include different versions of the include
347 directory.
351 Other Files
353 NOTE: There is no recommendation at this time for the best and
354 proper handling of, say, FOO-config types of files. Or non-code
355 types of files (e.g. things that typically get installed into areas
356 like /usr/shared).
357 Further thought and exploration is needed here.
363 Other Notes
365 It is expected that other libraries, besides those in the APR project, will want
366 to use the above definitions of versioning. This is quite fine, and those
367 libraries can simply reference this document. Its canonical location is:
369 https://apr.apache.org/versioning.html
373 -----------------------------------------------------------------------------------------------------------------------
374 Copyright © 2008, The Apache Software Foundation