~ubuntu-branches/ubuntu/intrepid/plplot/intrepid

INDEX
(1) GNU Privacy Guard (gpg).
(2) Installing a Local Copy of the PLplot Webpage.
(3) Creating a test tarball from trunk.
(4) Creating a PLplot Release.


(1) GNU Privacy Guard (gpg)
A brief summary of developer relevant gpg commands, see also:
http://webber.dewinter.com/gnupg_howto/
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)

(2) Installing a Local Copy of the PLplot Webpage.

It can be convenient for testing purposes to install a local copy of the 
PLplot webpage (http://plplot.sourceforge.net/index.html) on your machine.
The first step is to install Apache and PHP (if you don't already have 
them). You will also need to be able to build PLplot with the cairo device 
driver. After you have installed these items do the following three steps
(N.B. each with the same prefix for WWW_DIR but with a deliberately different 
suffix for WWW_DIR):

  1. Build a local version of the documentation and install it to the
     local copy of the PLplot webpage.  
     
     N.B. this build puts some documentation results into the source tree so
     we use a throwaway source tree for this.
     
     N.B. this build completely removes WWW_DIR on the local machine
     (localhost) so be careful how you specify the -DWWW_DIR option!

rm -rf /tmp/plplotdoc
mkdir -p /tmp/plplotdoc/build
cd /tmp/plplotdoc
svn export https://plplot.svn.sourceforge.net/svnroot/plplot/trunk \
plplot_source
cd /tmp/plplotdoc/build
cmake 
-DWWW_USER=username \
-DWWW_GROUP=group \
-DWWW_HOST=localhost \
-DWWW_DIR=/var/www/plplot/htdocs/docbook-manual \
-DCMAKE_VERBOSE_MAKEFILE=ON \
-DDEFAULT_NO_BINDINGS=ON -DDEFAULT_NO_DEVICES=ON \
-DPREBUILD_DIST=ON
-DBUILD_DOC=ON \
../plplot_source \
>& cmake.out
make prebuild_dist >& make_prebuild.out
     

  2. In the root directory of a throwaway copy of the PLplot source tree (say
     /tmp/plplotdoc/plplot_source from step 1 above) execute the following
     command:

     N.B. this command completely removes WWW_DIR on the local machine
     (localhost) so be careful how you specify WWW_DIR!

WWW_USER=username \
WWW_GROUP=group \
WWW_HOST=localhost \
WWW_DIR=/var/www/plplot \
./scripts/htdocs-gen_plot-examples.sh

  3. Then, in /tmp/plplotdoc/plplot_source/www execute the following command:

     N.B. this command completely removes WWW_DIR on the local machine
     (localhost) so be careful how you specify WWW_DIR!
make \
WWW_USER=username \
WWW_GROUP=group \
WWW_HOST=localhost \
WWW_DIR=/var/www/plplot/htdocs

Where username and group are your username and group.

If everything works as it should, you should be able to browse the local
site at:
http://127.0.0.1/plplot/htdocs/index.html

(3) Creating a test tarball from trunk

This optional 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.

(4) 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.

Using svn, commit the above changes.

(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.


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 command: 

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.


In the event that problems are found in PLplot during the release process, 
corrections should be made to trunk/ and then merged 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.

Install the documentation on the PLplot website:
cd /tmp/plplot-dist-prep/build_dir/doc/docbook/src
make www-install

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 the ChangeLog file (in the trunk/ directory):
svn log -v > ChangeLog.release

Edit ChangeLog.release to be the appropriate date range (i.e. only the
changes that were made since the last release should be included).


Upload the plplot-X.X.X.tar.gz.* files to the SF upload section

ftp upload.sourceforge.net #username is ftp, password is your e-mail address
cd incoming
bin
put plplot-X.X.X.tar.gz
put plplot-X.X.X.tar.gz.asc
quit

ftp does not provide any feedback re upload progress, so again, be patient.


Prepare a file release:

Login to sf.net.
Go to the PLplot project page.
Select file releases in the drop down admin menu at the top of the page.
Click add release at the bottom of the page.
Enter the new release name and click "create this release".

N.B. Release names guide our users to the release they want when they browse
our file release area.  The source release names should be of the form
"5.x.y Source" (e.g., "5.6.1 Source").  The reason for this suggestion is to
keep source release names distinct from binary release names.

In the file release GUI (Step1):
Browse to README.release in "Upload Release Notes".
Browse to ChangeLog.release in "Upload Change Log".
Select "preserve my pre-formatted text"
Click "Submit/Refresh"

In the file release GUI (Step2):
Select (and only select) the uploaded plplot files.
Click "Add Files and/or Refresh View"

In the edit file in release GUI (Step3):
For plplot-X.X.X.tar.gz select "any" for the processor type and "source.gz" for
the file type.
For plplot-X.X.X.tar.gz.asc select "any" for the processor type and
"other source" for the file type.

In the e-mail notification GUI (Step4):
Select that you are sure that you want to send an e-mail to those who are
monitoring the PLplot releases.

Prepare the release notes:
Return the PLplot project page
Select Admin -> News
Click on submit to create a new news item.
Load an old release news item in another browser window and use that as a 
template for creating your new release news item. Make sure that you get
the link to the release notes correct (none of the other links need to be
changed).
Click on submit.

Update the project web page, including the examples:
edit www/index.html to include a link to the latest release.
edit www/examples/index.html.in to reflect the current release number.
svn commit the updated pages.

Create a directory containing a fresh svn checkout of PLplot, including the 
www scripts. Run the following commands in that directory:
./scripts/htdocs-gen_plot-examples.sh
cd www
make

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.

DONE!!!