INDEX
(1) Install and test a local copy of the PLplot website.
(2) Upload the local website to SourceForge.
(3) Creating a PLplot Release.
(4) Publicity for the release announcement.
(5) Immediate preparation for next release cycle

(A1) GNU Privacy Guard (gpg)
(A2) Creating a test tarball from trunk
(A3) Correct computer time

(1) Install and test a local copy of the PLplot website:

(N.B. this step needs to be done first to insure the associated source tree
updates get into the release tarball, the svn tags version of the release,
and associated commit messages get into the ChangeLog for the
release.)

You should always generate and install from scratch a local copy of the
PLplot website on some ssh-accessible machine (normally your local machine).

If necessary, update the examples list in
scripts/htdocs-gen_plot-examples.sh. That list is used to generate the
website example-related files and copy the results to the website. The list
automatically controls what example source code is configured (for source
code that needs that), as well as what example plots and example thumbnails
are generated.  The list also automatically controls what examples-related
files are copied to the website.

Update the project web page, including the examples: edit
www/examples.php to reflect the forthcoming release version number and
any changes to the examples themselves (i.e. pages added or removed
from an existing example or entirely new examples).

Run (on a Linux host that is capable of building the documentation
for the source tree that has all local changes)

scripts/generate_website.sh

with no arguments.  The script asks you four questions, gives you a chance
to verify your answers, then does all the rest of it (downloading a
throwaway copy of the PLplot source code, building the documentation,
generating the announcements that are part of the base website, uploading
the base website, uploading the documentation, building the examples,
running the examples, uploading the example source code and example results)
automatically.  I (AWI) tested this script using the four answers

Summary:
USERNAME = irwin
GROUPNAME = irwin
HOSTNAME = raven
WEBSITE_PREFIX = /home/irwin/public_html/plplot

(raven is my local computer name, and /home/irwin/public_html is a location
where I can put various websites).  You can check for errors (e.g., due
to missing commands that need to be installed) by running

find /tmp/plplotdoc -name '*.out' |xargs grep -i error

You should install both apache and PHP on your computer.  For Debian Testing
(a.k.a. squeeze) that is done (as root) by installing libapache2-mod-php5
and enabling user directories using the command

a2enmod userdir

and editing /etc/apache2/mods-available/php5.conf as indicated in that
file to allow user directories for php.  I am not sure, but I believe
from some google results I found that editing of that file is also
necessary on modern versions of Ubuntu in order to allow php-based websites
like that of PLplot to work when installed in local user directories.

You will also need to install "xml-to" (in the xml-to debian package).

(When user directories are enabled this way, for the above case
/home/irwin/public_html/plplot/htdocs, browses as
http://raven/~irwin/plplot/htdocs/.)

I test http://raven/~irwin/plplot/htdocs/ by clicking on most links, checking
the documentation looks good, checking the examples look good and the
source code for each language for examples is accessible, etc.

N.B. scripts/generate_website.sh uses the local source tree where that
script resides (including all local changes) as the source tree for
generating the local website.  So there is no need to commit every
above example and version change until you are completely satisfied
with the local website.  But after you _are_ satisfied with the
local website you should commit all your changes so they are available
for generating the tarball and ChangeLog (see below) for this release.

(2) Upload the local website to SourceForge:

Once you are satisfied with the local website, you should upload it to
SourceForge with rsync.

For the above WEBSITE_PREFIX, here is what worked for me from my computer
with the hostname of raven where that WEBSITE_PREFIX directory was
created.

rsync -av --delete \
/home/irwin/public_html/plplot/htdocs/ \
airwin,plplot@web.sourceforge.net:htdocs 

Adjust for your username and WEBSITE_PREFIX.  The ",plplot" part of the
username makes sure you have the right group permissions and default website
directory location for PLplot.  

N.B. the trailing slash on the source directory is essential and means rsync
the contents of this directory with the contents of the destination htdocs
directory.  Without the trailing slash you would rsync the the contents of
the source directory with the contents of the htdocs/htdocs destination
directory which is not what you want to do.  

N.B. the --dry-run option for rsync is a god-send and tells you exactly what
will happen without actually doing it.

(3) Creating a PLplot Release:

Update the README.release file.

Update the docbook documentation to reflect any new drivers or new 
functionality that has been added to PLplot. Or alternatively, press those
who made the changes to update the documentation.

Update cmake/module/plplot_version.cmake to reflect the current version. Also,
follow the instructions in this file for updating the SOVERSION, the minor
number and the patch number.

IMPORTANT: commit all local changes to the repository so they
will be reflected in the ChangeLog, tagged version of the release,
and release tarball.

Prepare the ChangeLog.release file to keep track of all changes
made for the release.  (This destroys the ChangeLog.release file
from the previous release.)

# This makes the BASE used below correct.
svn update
svn log --revision BASE:<LAST_RELEASE_REVISION> --verbose  >| ChangeLog.release

where <LAST_RELEASE_REVISION> stands for the last revision number of
the previous release which can be found, e.g., by browsing
http://plplot.svn.sourceforge.net/viewvc/plplot/tags

Check that ChangeLog.release is in the appropriate date range (i.e. only the
changes that were made since the last release should be included) then
(IMPORTANT) commit it so it will also be available for the tagged
release version, the release tarball, etc.

Based on suggestions in the svn manual, the PLplot svn archive is configured
as follows:

/trunk/plplot
/tags/older_plplot_versions
/branches/??

For the release, you will be creating (and eventually committing) what is
essentially a branch of PLplot that is a record of the project at the time
of the release. This branch will be located in the /tags directory and
should follow the current naming convention, vX_Y_Z (v5_7_0 for example).

The easiest way to get started is to make a directory on your computer
called, for example plplot_releases. Then in this directory enter the
following command:

svn co https://plplot.svn.sourceforge.net/svnroot/plplot plplot

This will check out the *entire* plplot project, including all the old
versions. Strictly speaking this is not necessary, all you really need
are the trunk and the tags directories, but you'll only have to do this
once and hard drives are pretty big these days.

If you already have this directory, you will need to make sure that
trunk is up to date. In the trunk directory, type:

svn update

Now to create the branch for the new PLplot release, type the following
command in the root plplot directory:

svn copy trunk/ tags/vX_Y_Z

The commit the new tag:

cd tags/vX_Y_Z
svn commit -m "Adding a tag for the X.Y.Z release."

cd to tags/ and enter the following commands: 

export WWW_USER=your_sf_user_name
../trunk/scripts/make_tarball.sh -c -i /tmp/vX_Y_Z -t vX_Y_Z 2>&1 | tee build.log

This script will take a several minutes to execute and does not otherwise
provide a lot of feedback so it will appear as if it is doing nothing for
long periods of time (at least on a slower computer). Be patient. When the
script is finished, the release tarball will be available in the directory
/tmp/plplot-dist-prep/

The "-c" option says to unpack the created tarball, build it with "cmake" and
"make", then test that result with ctest.

The "-i /tmp/vX_Y_Z" specifies the install prefix for the tarball
test configure and runs "make install" after cmake, make and ctest. When the
above command finishes executing you should go to this directory and verify
that the examples build and that plplot_test.sh executes without errors.

The build will fail (without any warning messages on the console) if you 
do not have the necessary tools to build the documentation. It is a good 
idea to verify that you can build the documentation (-DBUILD_DOC=ON).

In the event that problems are found in PLplot during the release
process, corrections should be made to trunk/, the ChangeLog.release
file recreated and committed (see instructions above).  Then merge the
trunk version into the tags/vX_Y_Z branch as follows:

cd tags/vX_Y_Z
svn merge -r A:B /path/to/trunk

Where A and B specify the range of revisions in trunk to be applied
to tags/vX_Y_Z in the merge process. These can be determined by commit
messages.

Sign the release with your plplot Release Manager gpg key:
gpg --default-key YYYYYYYY --detach-sign --armor /tmp/plplot-dist-prep/plplot-X.X.X.tar.gz

A list of your GPG keys can be obtained using the command "gpg --list-keys".

Prepare a file release:

Login to sf.net.
Go to the PLplot SourceForge project page.

Upload the Release:
Select Files.
Click on the plplot folder & select "Add folder".
Enter the release name as the "New folder name:", e.g. X.Y.Z Source.
Click on the release folder pop-up menu & select "upload", upload the
release and the gpg signature file from /tmp/plplot-dist-prep/. This can
take a few minutes without much feedback.
Concatenate the README.release and ChangeLog.release files into a single 
README.release file.
Upload the concatenated README.release file.
Click on the "i" or "info" button to mark the tar.gz file as the default 
file to download for all platforms.


Create a news item for the Release:
Select Develop / News
Click "Admin", select any older News Item and copy the test.
Click "Submit"
  Enter "PLplot Release X.Y.Z" as the subject.
  Paste in the text from the older release as the Details.
    Be sure to update the text as appropriate, particularly
    the release numbers.


(4) Publicity for the release announcement.

Jerry: macresearch.org

Barbara Irwin: linuxtoday.com, lwn.net, lxer.com

(5) Immediate preparation for next release cycle

  a. Append the README.release file from the current release onto the front of
     the OLD-README.release file. This is done to preserve a record of the
     significant changes between versions of PLplot.
  b. Update README.release file to reflect significant changes made between
     the current release and the last release.



--- Appendix ---

(A1) GNU Privacy Guard (gpg)
A brief summary of developer relevant gpg commands, see also:
http://dewinter.com/gnupg_howto/english/GPGMiniHowto.html
man gpg

create a new key:
gpg --gen-key

list keys so that you can find the ID of the key you created:
gpg --list-keys

upload your (public) key to GPG key server so that others can obtain it to
verify your signature on the release tarball.
gpg --send-keys 6C58D1AC
(where 6C58D1AC is replaced with the appropriate value from the list-keys
command)


(A2) (Optional) Creating a test tarball from trunk

This step is only required if you have some concerns about how
recent changes may have affected the generated source tarball, and you want
to generate that tarball and test it _before_ you create a tag for the
release.  (The release process for the tag below also generates a tarball
from the tag directory and tests it which is why this trunk version of the
same is optional.)

cd /tmp
/path-to-trunk-source/scripts/make_tarball.sh \
-w https://plplot.svn.sourceforge.net/svnroot/plplot
-c -i /tmp/trunk_install -t trunk 2>&1 | tee build.log

The above exports the current trunk
and uses 

/tmp/plplot-dist-prep/build_dir

to build the distribution source tarball

and uses

/tmp/plplot-dist-prep/ctest_build_dir

to configure and build PLplot from the unpacked tarball, ctest the build
tree, and install the built PLplot in /tmp/trunk_install

Here are the *.out files generated by this process which should be checked.

/tmp/plplot-dist-prep/build_dir/cmake.out
/tmp/plplot-dist-prep/build_dir/make_prebuild_dist.out
/tmp/plplot-dist-prep/build_dir/make_package_source.out
/tmp/plplot-dist-prep/ctest_build_dir/cmake.out
/tmp/plplot-dist-prep/ctest_build_dir/make.out
/tmp/plplot-dist-prep/ctest_build_dir/ctest.out
/tmp/plplot-dist-prep/ctest_build_dir/make_install.out

Here is how the install location should be checked:

cd /tmp/trunk_install/share/plplotX.Y.Z/examples
make >& make_examples.out
./plplot-test.sh --help  #to see what kinds of tests can be run
./plplot-test.sh --device=psc
./plplot-test.sh --device=pscairo
./plplot-test.sh --device=pngcairo
./plplot-test.sh --device=png

etc.  Check the results with, e.g.,

display x01c.pngcairo.01
display x08c.pscairo

where "display" is the general image viewer from the imagemagick suite
of programmes.

(A3) Correct computer time

(While it is useful to have the correct time on your computer, this is no 
longer strictly necessary).
Verify that your computer has the right date and time using the command date.
The easiest way to make sure the time and date are correct is to do the 
following:
1. Install the debian ntpdate package.
2. Execute the command "/usr/sbin/ntpdate pool.ntp.org", which you will
   have to do as root.
This will immediately change your system clock. It is not recommended if you
have other apps running on your system that expect time to increase in a
smooth and linear fashion.

If you would like your computer to always have the correct time and date, you 
can install the debian ntp package, which must be properly configured to work.
Some notes about how to do this can be found in the PLplot mailing list 
archive. Look for the thread titled "PLplot 5.7.2 is now available" dated 
Jan 22/23 2007.