Codebase list erfa / f3e647f
Merge branch 'upstream' into debian Conflicts: RELEASE.rst configure.ac src/Makefile.am Ole Streicher 10 years ago
3 changed file(s) with 116 addition(s) and 23 deletion(s). Raw diff Collapse all Expand all
+107
-9
RELEASE.rst less more
1616
1717 * Update the version number in the `AC_INIT` macro of `configure.ac` to
1818 the version number you are about to release, and also update the version
19 mentioned in `README.rst`.
19 mentioned in `README.rst`. Follow the instructions in
20 `Version numbering` below.
21
22 * Update the version info of the shared library in the `ERFA_LIB_VERSION_INFO`
23 macro of `configure.ac`. Follow the instructions in `Version numbering` below.
2024
2125 * Commit these changes using ``git commit``, with a commit message like
2226 ``Preparing release v0.0.1``.
6569 Version numbering
6670 =================
6771
68 ERFA uses `semantic versioning <http://semver.org/>`_.
69
70 Given a version number MAJOR.MINOR.PATCH, increment the:
71
72 * MAJOR version when you make incompatible API changes
73 * MINOR version when you add functionality in a backwards-compatible manner
74 * PATCH version when you make backwards-compatible bug fixes
75
72 ERFA needs to provide two different version numbers. You need to update both.
73 The first is the
74 **package version number** or **version number** proper. ERFA uses
75 `semantic versioning <http://semver.org/>`_ to create this number.
7676 For more on this choice, see
7777 `liberfa/erfa#6 <https://github.com/liberfa/erfa/issues/6>`_.
7878
79 The second number is `shared libray version info`. When a program has been
80 linked with the ERFA shared library, the dynamic linker checks the version
81 info of the library requested by the program with those of the libraries
82 present if the system. This version info is important to binary distributions
83 (such as Linux distributions). ERFA uses `libtool versioning <http://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html>`_.
84
85
86 Package version number
87 ----------------------
88
89 Semantic versioning dictates how to change the version number according to
90 changes to the API of the library. In the case of ERFA the API is:
91
92 * The public C macros defined in erfam.h
93 * The names, return types, number of arguments and types of the functions in erfa.h
94
95 To update the package version, the release manager has to check the relevant
96 information about the release, such as:
97
98 * upstream SOFA documentation in http://www.iausofa.org/current_changes.html
99 * relevant bug reports in the github project page
100
101 If the version is given in the form MAJOR.MINOR.PATCH, then
102
103 * if there is a backwards incompatible change (function removed, types of
104 arguments altered, macros renamed...) then increase MAJOR by one and set
105 the others to zero.
106 * else if there is backwards compatible change (new function added or
107 new macro added) then do not change MAJOR, increase MINOR by one and
108 set PATCH to zero.
109 * else
110 you are either fixing a bug or making other improvements. Increase
111 patch by one and do not change the others.
112
113 Change the version number in the `AC_INIT` macro and in `README.rst`
114
115 Shared libray version info
116 ---------------------------
117
118 For the shared library version info, we are only interested in a subset of
119 the API, the **interfaces of the shared library**. As the C macros are
120 interpolated away at compile time, the interfaces in the ERFA
121 shared library are:
122
123 * The names, return types, number of arguments and types of the functions
124
125 Again, the release manager has to review the relevant information:
126
127 * upstream SOFA documentation in http://www.iausofa.org/current_changes.html
128 * relevant bug reports in the github project page
129
130 The shared library version info is stored in three numbers called *current*, *revision* and *age*. These numbers appear in the macro `ERFA_LIB_VERSION_INFO` in
131 the mentioned order.
132
133 If the version is given in the form CURRENT,REVISION,AGE then
134
135 * if there is a backwards incompatible change (function removed, types of
136 arguments altered...) then increase CURRENT by one and set
137 the others to zero (c,r,a -> c+1,0,0).
138 * else if there is backwards compatible change (new function added)
139 then increase both CURRENT and AGE by one, set REVISON to zero
140 (c,r,a -> c+1,0,a+1).
141 * else if the library code has been modified at all
142 then increase REVISION by one (c,r,a -> c,r+1,a)
143 * else
144 do not change the version info (c,r,a -> c,r,a)
145
146 Change the verion info in `ERFA_LIB_VERSION_INFO`
147
148 Examples
149 ---------
150 We start with ERFA version 1.0.0 and library version info 0,0,0
151
152 * SOFA makes a new release. A function is added and two functions change their
153 arguments. This is a backawars incompatible change, so the new package will
154 have version 2.0.0 and the shared library version info will be 1,0,0
155
156 * We forgot to add README.rst to the release. We make a new one. The change
157 is a bugfix (no API changes), the new release will be 2.0.1. The shared
158 library version is not modified (no changes in the library source code).
159
160 * SOFA makes a new release. They just add a new function. The new package
161 version will be 2.1.0. The shared library info will be 2,0,1 (both current
162 and age are incremented).
163
164 * SOFA makes a new relase fixing some bugs in the code without changing the
165 API. New package version is 2.1.1. The shared library version is 2,1,1
166
167 * A contributor finds a bug in ERFA. The fix doesn't change the API. New
168 package version is 2.1.2. The shared library version is 2,2,1
169
170 * SOFA makes a new release incorporating the bug fix and adding new functions.
171 The new package version is 2.2.0. The shared library version is 3,0,2
172
173 * SOFA makes a new release removing functions. This is a backawars
174 incompatible change, so the new package will
175 have version 3.0.0 and the shared library version info will be 4,0,0
176
79177 .. _erfa-fetch repository: https://github.com/liberfa/erfa-fetch
+7
-1
configure.ac less more
00 # Process this file with autoconf to produce a configure script.
11
22 AC_PREREQ([2.68])
3 AC_INIT([erfa],[1.0.0])
3 ## Follow the instructions in RELEASE.rst to change package version
4 AC_INIT([erfa],[1.0.1])
45 AC_CONFIG_SRCDIR([src/erfa.h])
56 AC_CONFIG_HEADER([config.h])
67 AC_CONFIG_MACRO_DIR([m4])
1112 LT_INIT
1213
1314 ERFA_NUMVER
15 ## Version info is in current : revision : age form
16 ## A library supports interfaces from current downto current - age
17 ## Revision is the version of the current interface
18 ## Follow the instructions in RELEASE.rst to change the version info
19 ERFA_LIB_VERSION_INFO(1, 0, 0)
1420
1521 # Checks for libraries.
1622 AC_SEARCH_LIBS([sin], [m], , AC_MSG_ERROR([cannot find math functions]))
+2
-13
src/Makefile.am less more
2626 ## Version info is in current : revision : age form
2727 ## A library supports interfaces from current downto current - age
2828 ## Revision is the version of the current interface
29 ## If the source code has changed at all, rev += 1
3029
31 #liberfa_la_LDFLAGS = -version-info 0:0:0
30 ## VI_ALL is set in the macro ERFA_LIB_VERSION_INFO in configure.ac
3231
33 #for erfa, we compute this version info. For ERFA x.y.z we set version-info
34 #to (x+y):z:y, as this reproduces the appropriate SONAME matching the
35 #library version number for semantic versioning
36 PKG_MAJ = `echo $(PACKAGE_VERSION) | cut -d . -f 1`
37 PKG_MIN = `echo $(PACKAGE_VERSION) | cut -d . -f 2`
38 PKG_BUG = `echo $(PACKAGE_VERSION) | cut -d . -f 3`
39 VI_CURR = $(shell expr $(PKG_MAJ) + $(PKG_MIN))
40 VI_REV = $(PKG_BUG)
41 VI_AGE = $(PKG_MIN)
42
43 liberfa_la_LDFLAGS = -version-info $(VI_CURR):$(VI_REV):$(VI_AGE)
32 liberfa_la_LDFLAGS = -version-info $(VI_ALL)
4433
4534
4635 ## Check program