forked from icl-utk-edu/papi
-
Notifications
You must be signed in to change notification settings - Fork 0
/
release_procedure.txt
358 lines (268 loc) · 15.2 KB
/
release_procedure.txt
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
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
Release Procedure for PAPI
==========================
Below is a step-wise procedure for making a PAPI release.
This is a living document and may not be totally current or accurate.
It is an attempt to capture current practice in making a PAPI release.
Please update it as appropriate.
One way to use this procedure is to print a copy and check off
the lines as they are completed to avoid confusion.
================================================================================
__ 0a. Notify developers that a release is imminent and the repository should be
considered frozen. Check buildbot / make fulltest results to make sure
the codebase is bug-free.
Before running 'make fulltest', ensure you do NOT configure PAPI using
'--with-debug=yes'. This forces -O0 which will cause some the papi_tot_cyc.c
test to fail. We run our 'make fulltest' with no components installed (other
than the defaults). Several components require specialized hardware or OS or
sudo privileges to operate.
You should use '--with-debug=yes' if you wish to do any valgrind testing for
memory leaks. You can conduct such tests running the code
./validation_tests/memleak_check.c using valgrind. You may need to load a
module to use valgrind.
BEFORE YOU BEGIN: Step 2d will require access to the papi website directory,
so all these steps should be done on a machine that has it. Most recently we
updated using methane.icl.utk.edu, where /nfs/www/icl/projectsdev/papi/docs
was accessible. The sysadmin must give you write permission. This directory
should be available on all machines but Saturn, so do not use Saturn!
You must also be on a machine that will let you rebuild the manual pages.
This requires doxygen version 1.8.5. See step 2a. You can check the version
with 'doxygen -v'.
The website directory may be 'automount'. That means you cannot see it with
'ls', it will not be searched by 'find'. You must change to the directory
for it to automount. For example,
'pushd /nfs/www/icl/projectsdev/papi/docs' to get it mounted.
(If this fails, you don't have access, discuss with your sysadmin.)
'popd' to return to your previous directory, THEN you can
'ls /nfs/www/icl/projectsdev/papi/docs' and see the files.
--- Modified with 6.0.0 to use a Pull Request, to allow review of changes
before committing.
__ 0b. Fork the repository. it is at:
https://bitbucket.org/icl/papi/src/master/
on the left columnar menu, click '+', then select 'Fork Repository'.
For the name, presume papi-release-X-Y-Z-t. Replace X,Y,Z with the
appropriate numerals.
__ 0c. Clone the fork. This will depend on your user ID, but after the fork
you can get the address for the clone by clicking "clone" at the top
of the forked version.
Example: git clone https://[email protected]/icl/papi.git papi-6.0.0
__ 0d. Change to the directory. Example: cd papi-6.0.0
__ 1. Update any documentation that may have changed. Pay particular attention
to INSTALL.txt.
__ 2. Check/Change the version number in:
papi.spec,
src/papi.h,
src/configure.in,
src/Makefile.in,
doc/Doxyfile-common (as PROJECT_NUMBER);
and commit to the repo, along with any other changed files.
Do not "git push" until autoconf is run (Step 3). You will have to run it,
you just changed configure.in, which is the reason to run autoconf.
The version number may already have been updated after the last release,
if so you can skip these edits, but do commit any other files changed.
-- 2a. Ensure you have doxygen 1.8.5. 'doxygen -v'.
For release 6.0.0, we used methane.icl.utk.edu, doxygen 1.8.5 was in /usr/bin.
you can check using 'doxygen -v' to get the version.
If it isn't found, find the doxygen directories and add it to $PATH. Example:
'find /usr -name "doxygen" 2>/dev/null'
'export PATH=/[PathFound]:$PATH' (use actual path for [PathFound].)
'doxygen -v' (To Test)
-- 2b. Rebuild the doxygen manpages.
'cd doc && make && make install'
You will want to check if anything needs to be committed to git.
(Usually the $(papi_dir)/man/man1 and man3 directories).
doxygen may generate some extraneous files in man1 and man3; eg
man/man1/_home_youruserid_*.*
man/man3/_home_youruserid_*.*
Remove these. Be careful of the directory! These ALSO exist in
doc/man/man1 and doc/man/man3 (where they were built).
Those are NOT the ones to remove, and not the ones to ADD in the next step.
Then you can go to each directory and add all files:
>cd papi/man/man1
>git add *
>cd papi/man/man3
>git add *
---- Step 2d will require access to the webdir. The website files are not
---- saved as part of the repository, they are updated directly.
-- 2c. Rebuild the website docs.
We use Doxyfile-html for this, that is a configuration file in papi/doc
that will be used by Makefile.
'newgrp papi' (newgrp is a linux command, it changes your defacto group to
papi, starting a new shell.
'cd doc && make clean html'
-- 2d. Update the web dir (currently /nfs/www/icl/projectsdev/papi/docs).
for the example below, 'webdir' = '/nfs/www/icl/projectsdev'.
You may wish to do a diff between this directory and the papi directory to
ensure you are replacing the correct files.
>diff webdir/papi/docs/* papi/doc/html/*
Cleanup web dir install new files
( /bin/rm -rf /webdir/papi/docs/* )
( cp -R doc/html/* /webdir/papi/docs )
( chmod -R 775 /webdir/papi/docs )
__ 3. If 'configure.in' is changed, we must generate a new 'configure' file.
Run autoconf (2.69), it reads configure.in and creates a new configure.
We have an issue with autoconf; on different machines the same version (2.69)
can produce different files; some include 'runstatedir' lines, others do not.
We want those removed. All new changes must now be done on
saturn.icl.utk.edu with autoconf 2.69.
NOTE: Using an autoconf version >2.69 will work, but will produce an
inordinate number of extraneous differences between versions.
You can check the version # with 'autoconf -V'
Release 6.0.0.1 was done on saturn.icl.utk.edu with autoconf 2.69.
__ 4. Create a ChangeLog for the current release.
We use a python script gitlog2changelog.py to generate is for us.
It expects the tag of the last release as an argument.
./gitlog2changelog.py papi-a-b-c-t
mv ChangeLog ChangeLogP600.txt (use your own version).
__ 5. Scan the ChangeLog to remove extraneous fluff, like perfctr imports.
__ 6. Modfy RELEASENOTES.txt to summarize the major changes listed in the log.
__ 7. Add ChangeLogXYZ.txt to git and commit both ChangeLogXYZ.txt and
RELEASENOTES.txt.
__ 8. Push the repository back to the fork. 'git push'.
__ 9. Go back to the fork's online page, and create a pull request.
On the left-hand columnar menu, click '+', and select the
"create pull request" menu item.
Then wait for that to be reviewed, approved, and merged.
Once it is merged, no other pull requests should be approved, until the
following steps are completed!
------BRANCHING AND TAGGING
__ 10. After the pull request is merged: Clone the new PAPI.
first, remove or rename any existing papi/ directory. Then
'git clone https://[email protected]/icl/papi.git' (with your own git user ID).
__ 11. Change to the papi directory, 'cd papi'.
If this is not an incremental release, branch git.
'git checkout -b stable-6.0' (change version as needed).
__ 12. Tag git: papi-X-Y-Z-t.
Example: 'git tag -a papi-6-0-0-t'
__ 13. Push the tag to the central repo. Examples:
IF you created a new branch: 'git push --tags origin stable-6.0' (should match step 11).
OTHERWISE: 'git push --tags'
This will ask for a comment on the tags. I can't find where that gets displayed on the
repository site, but 'Release PAPI-6-0-0-t' is sufficient. (your own version of course).
__ 13a. Double check. Go to the repository. Look at Branches; ensure you select 'all branches',
if you branched, the branch should be shown.
Ensure your tag appears on the list of Commits.
------BUILD A TARBALL.
__ 14. Create a fresh clone of the papi repository, under a directory name including the
release number. This is important, we will delete the '.git' file for the tarball,
so this new directory will not longer be under git. Example:
'git clone https://bitbucket.org/icl/papi.git papi-6.0.0'
'cd papi-6.0.0'
Note. If you created a new branch, ensure the clone contains
your last commit and ChangeLog. If not, something went wrong with steps 4-8.
__ 15. Delete any unneccessary files or directories particularly .doc and .pdf
files in the /doc directory. We use a script for this, it deletes itself.
'sh delete_before_release.sh'
NOTE: This deletes the .git directory! you will not be able to commit or
push any changes in this directory once this script is run.
__ 16. tar the directory; example:
'tar -cvf papi-X.Y.Z.tar papi-X.Y.Z' (using release number for X-Y-Z).
__ 17. zip the tarball:
'gzip papi-X.Y.Z.tar'
__ 18. Copy the tarball to the website. Example:
'cp papi-X.Y.Z.tar /nfs/www/icl/projects/papi/downloads/.'
current directory: /nfs/www/icl/projects/papi/downloads
previously: gonzo:/mnt/papi/downloads
previously: /silk/homes/icl/projects/papi/downloads
__ 19. Check permissions on the tarball. 664 is good. (-rw-rw-r--).
__ 19a. Check that the proper link where folks can download the tarball
is functional. It should look like:
http://icl.utk.edu/projects/papi/downloads/papi-X.Y.Z.tar.gz
---- The following steps are typically done by the person responsible
---- for the website, NOT the programmer completing the release. But
---- final steps are done by the programmer, after these are completed.
__ 20. Create a link with supporting text on the PAPI software web page.
Creeate an entry on the PAPI wiki:
https://bitbucket.org/icl/papi/wiki/PAPI-Releases.md
announcing the new release with details about the changes.
__ 21. Create a News item on the PAPI Web page.
---- The following steps are typically done by the PAPI PIs or management.
---- At this writing, Heike Jagode and Anthony Danalis.
__ 22. Email the papi developer and discussion lists with an announcement.
---- FINAL STEPS: To be done by the Programmer making the release.
---- Bump version number, update release procedures (after you know they
---- worked!) This is to ensure more development commits (that may not
---- be fully tested) will not be in the release version of the repository.
__ 23. Using steps 0b,0c,0d, make ANOTHER fork of the repository, clone it,
and change to that directory. Example, papi-6-0-1.
__ 24. Repeate Step 2 (ONLY Step 2, not 2a, etc) to bump the version number in
the repository AFTER the release changing Z to Z+1. Example:
papi-6-0-0 to papi-6-0-1. The following files must be edited:
papi.spec,
src/papi.h,
src/configure.in,
src/Makefile.in,
doc/Doxyfile-common (PROJECT_NUMBER)
__ 25. Repeat Step 3, to create a new configure, preserving runstatedir lines.
__ 25a. If these 'release_procedure.txt' instructions need to be updated, fix them now.
__ 26. Add changed files, Commit and Push.
(use 'git status -uno' to see files that need to be added with 'git add filepath').
'git commit -m "Updated version to 6.0.1 after the release'
'git push'.
__ 27. Repeat step 9, to create a pull request for review.
================================================================================
Patch Procedure for PAPI January 29, 2010
Below is a step-wise procedure for making a PAPI patch.
One way to use this procedure is to print a copy and check off
the lines as they are completed to avoid confusion.
================================================================================
__ 0. Make sure you're on the branch you want to patch against.
> git branch
* stable-5.0
__1. Generate the patch.
> git diff -p papi-5-0-0-t stable-5.0 > papi-5-0-1.patch
__ 2. Apply the patch.
> wget http://icl.cs.utk.edu/projects/papi/downloads/papi-5.0.0.tar.gz
> tar xzf papi-5.0.0.tar.gz && cd papi-5.0.0
> patch -p1 ../papi-5-0-1.patch
__ 3. If the patch applied cleanly, build and test on affected platforms;
otherwise clean up the patch and try again.
__ 4. Copy the diff file to icl:/sw/www/icl/projects/papi/downloads/patches
__ 5. Check permissions on the diff. 644 is good.
__ 6. Create a link with supporting text on the PAPI software web page.
__ 7. Create a News item on the PAPI Web page.
__ 8. Email the papi discussion list with an announcement.
__ 9. Post the announcement on the PAPI User Forum.
================================================================================
Bug Fix Release Procedure for PAPI
Below is a step-wise procedure for creating a bug fix release tarball.
One way to use this procedure is to print a copy and check off
the lines as they are completed to avoid confusion.
================================================================================
__ 0. Clone the PAPI repo and checkout the release branch.
> git clone https://<your_login>@bitbucket.org/icl/papi.git
For the first bug fix release do:
> git checkout stable-6.0
For further bug fix releases create a branch from the last bug fix release:
> git checkout tags/papi-6-0-0-1-t -b papi-6-0-0-2
__ 1. Make sure you're on the branch you want to apply bug fixes
> git branch
* stable-6.0
__ 2. Apply bug fixes. If those fixes are already applied in the master branch,
you can do 'git cherry-pick <commit#>'. If the commit was a merge use "-m 1",
e.g.:
> git cherry-pick -m 1 95c2b15
> git cherry-pick -m 1 7acc7a5
__ 3. Build and test your changes on different platforms.
__ 4. Create the tag papi-X-Y-Z-N-t (N is an incremental bug fix identifier)
Example:
> git tag -a papi-6-0-0-1-t
__ 5. Push your changes:
> git push --tags
__ 6. Create a fresh clone of the papi repository, under a directory name including
the release number. Do not use your login this time!
> git clone https://bitbucket.org/icl/papi.git papi-6.0.0.1
__ 7. tar and zip the directory; example:
> tar -czf papi-6.0.0.1.tar.gz papi-6.0.0.1
__ 8. Copy the tarball to the webserver.
> scp papi-6.0.0.1.tar.gz methane:/nfs/www/icl/projects/papi/downloads
__ 9. ssh to methane and adjust permissions on the tarball. 664 is good. (-rw-rw-r--).
> ssh methane
> cd /nfs/www/icl/projects/papi/downloads
> chmod g+w papi-6.0.0.1.tar.gz
__ 10. Check that the proper link where folks can download the tarball
is functional. Example:
> wget http://icl.utk.edu/projects/papi/downloads/papi-6.0.0.1.tar.gz
__ 11. Create a link with supporting text on the PAPI software web page.
Create an entry on the PAPI wiki:
https://bitbucket.org/icl/papi/wiki/PAPI-Releases.md
announcing the new release with details about the changes.