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,
   it is easiest to do all this on a machine that has it. Most recently we
   updated using harry.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; but it can
   be 'automount'. That means you can't see it with 'ls', you need to
   'cd /nfs/www/icl/projectsdev/papi/docs' to get it mounted, and THEN you can
   see it with 'ls'. 

__ 0b. Update your local copy from git to make sure you have all changes.
	git pull

__ 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 number may already have been updated after the last release, if so, skip this step.

-- 2a. 	You must find a machine to rebuild the doxygen pages.  We have been using
         doxygen 1.8.5. This is available on Saturn, and harry.icl.utk.edu. Note on
         Saturn there is also a module doxygen, with version 1.8.15. Don't use the older
         version without a reason; do a 'module list', and if doxygen is loaded, 
         'module unload doxygen'; then 'doxygen -v' to double check.

   For release 5.7.0, we used harry.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. 
   e.g. 'find /usr -name "doxygen" 2>/dev/null' then 'export PATH=/usr/bin/doxygen-1.8.5/bin:$PATH'
   (substituting whatever path was actually found).

-- 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 exist in doc/man/man1 and doc/man/man3.
   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 *

   Note: Step 2d will require access to the webdir. Since these files are not 
         saved as part of the repository, 
-- 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, this changes your defacto group to papi (starts a new shell)
	( cd doc && make clean html )

-- 2d.  Update the web dir, wherever it may be. On harry.icl.utk.edu, it is found on 
	/nfs/www/icl/projectsdev/papi/docs, but the sysadmin must give you write permission.
	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.
    First, make a copy of the existing file in papi/src; eg 'cp configure old_configure'.
    Then 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 in there. If they are missing from the new configure, we need
    to add them in. We do that by building a patch we can apply.

    # Produce a diff file, newly-generated configure, to previous configure,
    # that had the runstatedir stuff in it.
    >  diff configure ~/papi/src/old_configure  >configure.diff

    # Edit the diff file. Delete changes that would mess with the version.
    # Keep only the change that are about adding in runstatedir. Examples
    # of what to keep in the diff file; a change, and an add.
    # 1234c1245
    # < libdir localedir mandir
    # ---
    # > libdir localedir mandir runstatedir
    # 1386a1398
    # > --runstatedir=DIR modifiable per-process data [LOCALSTATEDIR/run]
    > vim configure.diff

    # Backup the newly created configure, in case you mess this up.
    > cp configure save_configure

    # Patch the newly created configure, to add in runstatedir stuff.
    > patch configure configure.diff
    
    # Double check. search for runstatedir.
    > vim configure

    # Clean up.
    > rm configure.diff  old_configure  save_configure

	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
	One possible machine with 2.69 is saturn; harry.icl.utk.edu also has 
	an autoconf with 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 ChangeLogP4XYZ.txt

__ 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.	If this is not an incremental release, branch git.
	git checkout -b stable-X.Y [starting point eg master]

__ 9. 	Tag git: papi-X-Y-Z-t.
	git tag -a papi-X-Y-Z-t

__ 10. 	Push everything to the central repo.
	git push --tags
	-- or -- If you've created a new branch.
	git push --tags origin stable-X.Y:
        May also need to do a 'git push' NOW to get the master branch updated
        (follow instructions returned from git).

__ 11. 	Create a fresh clone of the papi repository.
	> git clone https://bitbucket.org/icl/papi.git papi-X.Y.Z
	> cd papi-X.Y.Z
       	Note. If you created a new branch, check if the clone contains
       	your last commit and ChangeLog.  If not, you may need to switch
       	to the master, merge the branch and push.  
      	( ## if new branch ## git checkout master; git merge stable-X.Y; git push )
       
__ 12. 	Delete any unneccessary files or directories
	particularly .doc and .pdf files in the /doc directory
	Things needed in /doc {Doxyfile, Doxyfile-everything}
        You can use the delete_before_release.sh script for this.
	NOTE: This deletes the .git directory, don't release out of your normal
	work directory, you will lose all the marbles this way.

__ 13. tar the directory:
	> tar -cvf papi-X.Y.Z.tar papi-X.Y.Z

__ 14. zip the tarball:
	gzip papi-X.Y.Z.tar

__ 15. Copy the tarball to the website; on harry.icl.utk.edu this is 
       currently:  /nfs/www/icl/projects/papi/downloads
       previously: gonzo:/mnt/papi/downloads
       previously: /silk/homes/icl/projects/papi/downloads

__ 16. Check permissions on the tarball. 664 is good.

NOTE:  Steps 17 and 18 are typically done by the person responsible
       for the website, not the programmer completing the release. 

__ 17. Create a link with supporting text on the PAPI software web page.

__ 18. Create a News item on the PAPI Web page.

NOTE:  Steps 19 and 20 are typically done by PAPI PIs or management 
       (at this writing Heike Jagode and Anthony Danalis). 

__ 19. Email the papi developer and discussion lists with an announcement.

__ 20. Post the announcement on the PAPI User Forum.

__ 21. Bump the version number in the repository AFTER the release (look at step 2)
       papi.spec, src/papi.h, src/configure.in, src/Makefile.in, doc/Doxyfile-common (PROJECT_NUMBER) 
       Regenerate the configure using autoconf 2.69. Then commit.
       ( git commit -m "Updated version to X.Y.Z after the release"  doc/Doxyfile-common papi.spec \
          release_procedure.txt src/Makefile.in src/configure src/configure.in  src/papi.h )
       This is to ensure more development commits (that may not be fully tested)
       will not be in the release version of the repository.

================================================================================

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.
