forked from OSGeo/PROJ
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathHOWTO-RELEASE
260 lines (171 loc) · 9.02 KB
/
HOWTO-RELEASE
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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
Preparing a PROJ Release
===============================================================================
Preparing a PROJ release is a three-step process. Before the actual release is
published we want to issue one or more release candidates to ensure that the
code is in fact ready to be released. That is step one. Step two starts when a
release candidate has been selected for promotion to final release. Step three
updates version numbers in the master branch to avoid confusion between
released code and code still in development.
The three phases are described below.
1 Release candidate
===============================================================================
At least one release candidate is necessary before the final release is
published. In case more than one release candidate is needed most steps below
can be skipped depending on what prompted the release candidate 1+n. Steps 1.6
and 1.7 are mandatory for all release candidates, otherwise it will in most
cases only be necessary to update the NEWS section (1.3).
Release candidates should be released about a week before the final release is
scheduled. When preparing major version releases it may be wise to issue the
release candidate earlier than that.
When a release candidate has not prompted any request for changes in 48 hours,
a motion for promotion to final release should be issued on the PROJ mailing
list. The PROJ PSC guidelines describes the rules for passing a motion.
1.1 Update ABI version numbers:
-------------------------------------------------------------------------------
In case of a un-planned maintenance release, make sure that version numbers are
properly updated: see 3.1
Determine the ABI version number. It consists of "current:revision:age". Follow
the steps below to determine the values in CMakeLists.txt:
- If the library source code has changed at all since the last update,
then increment PROJ_LIBTOOL_REVISION (c:r:a becomes c:r+1:a).
- If any interfaces have been added, removed, or changed since the last
update, increment PROJ_LIBTOOL_CURRENT and set PROJ_LIBTOOL_REVISION to 0.
- If any interfaces have been added since the last public release, then
increment PROJ_LIBTOOL_AGE.
- If any interfaces have been removed since the last public release, then
set PROJ_LIBTOOL_AGE to 0.
*Commit the changes to master.*
1.2 Update man pages
-------------------------------------------------------------------------------
Man pages are (mostly) automatically generated from the Sphinx docs. Follow
these steps:
- Temporarily update `version` and `data_version` in `docs/source/conf.py`
- run `scripts/update_man.sh`
- Revert version number in `docs/source/conf.py`
The `update_man.sh` script builds the man pages and commits the update man pages
to master.
1.3 Write release notes
-------------------------------------------------------------------------------
Update `NEWS` with descriptions of the changes since the last release.
Hopefully issues and pull requests that go into the new release have been
properly tagged with the milestone for the current release.
End the section by thanking the authors that contributed to the release. Get a
sorted list of contributors in descending order of activity:
```
git shortlog -sn x.y.z..HEAD | tac | awk '{$1=""; print $0}'
```
where `x.y.z` is the tag of the previous release. You may need to edit the list
slightly since not all authors has properly configured their names in git.
*Commit the changes to master.*
1.4 Update `CITATION`
-------------------------------------------------------------------------------
If needed, update the year in `CITATION`.
*Commit the changes to master.*
1.5 Update `PROJ_DATA.VERSION`
-------------------------------------------------------------------------------
If the database references data from an updated PROJ-data package, update
`PROJ_DATA.VERSION` in `data/sql/metadata.sql`.
*Commit the changes to master.*
1.6 Create maintenance branch
-------------------------------------------------------------------------------
*Skip this step if you are preparing a patch release or RC2 and later.*
Create the branch:
```
git branch x.y
```
where `x` is the major version number and `y` is the minor version number. Bug
fixes found in the release candidates should be pushed to master and
subsequently cherry-picked to the maintenance branch.
*Push branch upstream.*
1.7 Prepare and upload archives
-------------------------------------------------------------------------------
Checkout the GitHub repo to an isolated local directory to package files only
tracked in git. Then, run CMake and build source distributions:
```
BRANCH_NAME=master
git clone --depth 1 --branch $BRANCH_NAME \
https://github.com/OSGeo/PROJ.git PROJ-$BRANCH_NAME
cd PROJ-$BRANCH_NAME
mkdir _build && cd _build
cmake -D BUILD_TESTING=OFF ..
cmake --build . --target dist
```
Rename the archives and generate MD5 sum files:
```
mv proj-x.y.z.tar.gz proj-x.y.zRCn.tar.gz
mv proj-x.y.z.zip proj-x.y.zRCn.zip
md5 proj-x.y.zRCn.tar.gz > proj-x.y.zRCn.tar.gz.md5
md5 proj-x.y.zRCn.zip > proj-x.y.zRCn.zip.md5
```
Upload to the OSGeo download server:
```
scp proj-x.y.zRCn.* warmerdam@download.osgeo.org:/osgeo/download/proj
```
Adjust version numbers and usernames accordingly.
1.8 Announce the release candidate
-------------------------------------------------------------------------------
Announce the release candidate on the PROJ mailing list.
1.9 Promotion to final release
-------------------------------------------------------------------------------
When you are confident that the latest release candidate is ready for promotion
to final release a motion for promotion should be issued on the PROJ mailing
list. Allow for a minimum of 48 hours for voting time.
2 Final release
===============================================================================
Barring a successful promotion process we can proceed with the final release.
2.1 Prepare and upload archives
-------------------------------------------------------------------------------
See step 1.6 above. Do not rename the archives with RC postfixes.
2.2 Update website
------------------------------------------------------------------------------
- Add the release notes from `NEWS` to `docs/source/news.rst`
These vim substitutions are helpfull when converting NEWS to rst:
:s!(\#\(\d\{4}\))!(`\#\1 <https://github.com/OSGeo/PROJ/issues/\1>`_)!
:s/^o/*/
- Update download links in `docs/source/download.rst`
- Update `$TRAVIS_BRANCH` in `travis\after_success.sh` to new maintenance
branch.
*Commit the changes to master and cherry-pick into maintenance branch.*
When pushed upstream the website will be update to the current version.
2.3 Tag the release
-------------------------------------------------------------------------------
Tag the release with:
```
git tag -a -m "Create tag x.y.z" x.y.z
git push --tags
```
2.4 Prepare the release on GitHub
-------------------------------------------------------------------------------
When the new tag is pushed upstream GitHub picks up that a new release has been
issued. Update the new release on https://github.com/OSGeo/PROJ/releases with
the release notes from `NEWS` and add the prepared source distribution archives
to the release (otherwise GitHub will just package the entire repository - we
don't want that).
2.5 Announce the new release
-------------------------------------------------------------------------------
The release should be announced on PROJ and MetaCRS mailing lists. Additionally
the release announcement should be sent to news_item@osgeo.org which will add
the announcement to osgeo.org and other OSGeo communication channels.
Make some noise on Twitter and other relevant social media.
3 Post final release
===============================================================================
3.1 Update version numbers
-------------------------------------------------------------------------------
PROJ uses [semantic versioning](http://semver.org/). Depending on the changes
in the release will be either a major, minor or patch release. Update the
version numbers in the files.
- src/proj.h: Update PROJ_VERSION_MAJOR, PROJ_VERSION_MINOR and
PROJ_VERSION_PATCH.
- src/release.cpp: Update date to the scheduled release date.
- CMakeLists.txt: Update proj_version()
- docs/source/conf.py: Update version number
*Commit changes. Either to master or maintenance branch depending on the nature
of the release.*
3.2 Disable website deployment when releasing a new non-bugfix version
-------------------------------------------------------------------------------
If the previous active version was, let's say, 6.1 and the new version is, let's say, 6.2,
then checkout 6.1 branch, and in travis/after_success.sh, remove the code
that causes commits to 6.1 to cause a website refresh, that is remove the
code under `if test "$TRAVIS_SECURE_ENV_VARS" = "true" -a "$TRAVIS_BRANCH" = "6.1"; then`.
Also edit docs/source/conf.py to change the active branch for documentation
in the `github_version` variable.