INDEX
** Update versions
** Prepare a (preliminary) version of the ChangeLog file for this release
** Prepare the README.release file and/or press those who have made
   changes in this release cycle to update that file
** Prepare and test the documentation
** Check and potentially fix internal consistency
** Update website-related files
** Install and test a (preliminary) local copy of the PLplot website
** Update this file (README.Release_Manager_CookBook)
** Create (a preliminary version of) the release tarball and check the
   result for errors
** Do comprehensive test of PLplot
** Install and test a local copy of the PLplot website
** Upload the local website to SourceForge
** Create ChangeLog.release
** Create the PLplot Release
   ++ Preliminaries
   ++ Create a final release tarball and check the result for errors
   ++ Tag the release
   ++ Sign the release with your plplot Release Manager gpg key
   ++ Verify the release tarball signing
   ++ Make a SourceForge file release
** Publicize the release announcement
** Prepare immediately for the next release cycle

INDEX for Appendix
** GNU Privacy Guard (gpg)
** Correct computer time
** System prerequisites for viewing local website
** Fix website permissions

N.B. the order of steps below is important because of the dependencies
between the steps which are noted (except for the generation of the
final release tarball and ChangeLog which depend on virtually all
prior steps).
_________________________________________________________________________

** Update versions

This step depends on no others.

Update PLplot version in www/examples.php.  Also follow the
instructions in cmake/modules/plplot_version.cmake to update all
version information.
_________________________________________________________________________

** Prepare a (preliminary) version of the ChangeLog file for this release

This step does not depend on other steps.

git log --name-status --reverse <commit_id>..master >| ChangeLog.release_preliminary

where <commit_id> is the last commit id of the log of commits for the
previous release cycle (i.e., d4fdf0bab for the 5.10.0 release).

Note the "_preliminary" suffix to distinguish this from the final
result below which will contain (if all goes well in the steps below)
a record of all but the last commit (of the ChangeLog itself) for this
release.

Note because of the --reverse option above the order of this log will
be in chronological order.  But it is traditional for the final
version of this file to have the result in default reverse
chronological order so the --reverse option is not used in that case
(see below).

_________________________________________________________________________

** Prepare the README.release file and/or press those who have made
   changes in this release cycle to update that file

This step depends on the step above entitled

"Prepare a (preliminary) version of the ChangeLog file for this release".

To double-check that file is complete with regards to all major
developments during this release cycle, skim all the commit messages in
ChangeLog.release_preliminary determined above.
_________________________________________________________________________

** Prepare and test the documentation

This step depends on the "Update versions" step above.

Update the doxygen documentation (in our source code) and DocBook
documentation (in doc/docbook/src) to reflect any changes (new drivers
or new PLplot functionality) in the current release cycle.  Or
alternatively, press those who made the changes to update the
documentation.  Generate and test our doxygen form of documentation
following the instructions in doc/README.doxygen.

Update doc/docbook/src/CMakeLists.txt to reflect the best estimate
of the release date that will be used in the documentation build.

Update, generate and test our Docbook documentation following the
instructions in doc/docbook/README.developers.
_________________________________________________________________________

** Check and potentially fix internal consistency

This step depends on the step above entitled 

"Prepare and test the documentation".

Some of the files in the source tree are generated from other files
in the source tree using build-system targets.  All targets that
have "check" in the name prefix are these kind of targets.  Also,
some of the checks require special setup or take too long for the
general case, and these will be configured only for the
-DADD_SPECIAL_CONSISTENCY_CHECKING=ON case.

So use the above cmake option, and then for a complete list of
checks run

make help |grep '... check' |sort

in the build tree.  The current result of that command should be

... check_all
... check_api_xml_consistency
... check_f95_parameters
... check_plplot_h.inc
... check_plplotcapi_defines
... check_swig_documentation
... check_tcl_parameters

Note, one of these targets (check_plplot_h.inc) only exists 
because -DADD_SPECIAL_CONSISTENCY_CHECKING=ON implies
-DGENERATE_PLPLOT_H_INC=ON by default which in turn requires
that at least the OCaml version of the Perl regular expression library
be installed.  (On Debian the associated package name is
libpcre-ocaml-dev.)  Normally, GENERATE_PLPLOT_H_INC is OFF by default
to reduce build dependencies.

To actually do the internal consistency checks, run each of the above
targets by running the check_all target.  Each individual check target
typically generates a file in the build tree which is
then compared (using the Unix cmp command) with the file that is being
checked in the source tree.  If the two files are inconsistent (which
can be caused by documentation updates, for example), the cmp command
complains, and you should follow up by doing a diff between the two
files to confirm that the changes are reasonable followed by copying
the build-tree version of the file on top of the source-tree version
and committing the source-tree version.  When this process is completed,
all the above targets should run with no cmp or other errors/warnings
at all, e.g.,

software@raven> make check_all
Check that doc/docbook/src/api.xml is consistent with include/plplot.h
Built target check_api_xml_consistency
Check that bindings/swig-support/swig_documentation.i is consistent with doc/docbook/src/api.xml
Built target check_swig_documentation
Check that numerical #defines in bindings/swig-support/plplotcapi.i are consistent with the numerical #defines in include/plplot.h
An error for this target implies the numerical #defines section of bindings/swig-support/plplotcapi.i needs updating following the directions in that file
Built target check_plplotcapi_defines
Check that bindings/f95/plplot_parameters.inc is consistent with the #defines in bindings/swig-support/plplotcapi.i
Built target check_f95_parameters
Check that bindings/tcl/plplot_parameters.h is consistent with the #defines in bindings/swig-support/plplotcapi.i
Built target check_tcl_parameters
Check that bindings/ocaml/plplot_h.inc is consistent with bindings/ocaml/touchup.ml and bindings/ocaml/plplot_h
Built target check_plplot_h.inc
Built target check_all

_________________________________________________________________________

** Update website-related files

This step does not depend on other steps.

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 any changes to the examples themselves
(i.e. pages added or removed from an existing example or entirely new
examples).

Note, the xmlto package that must be installed in order to generate
the DocBook documentation (see doc/docbook/README.developers referred
to above) is also used to generate some of our older release
announcements for the website, and could also be used to generate
present release announcements for the website if desired.  See
www/announce/README for just how easy this step would be.
_________________________________________________________________________

** Install and test a (preliminary) local copy of the PLplot website

This step depends on the steps above entitled

"Prepare and test the documentation" and
"Update website-related files"

Also you should use your best estimate of the UTC release_date
which is configured as RELEASE_DATE in doc/docbook/src/CMakeLists.txt.
That value will likely require modification to generate the final
website result below.

N.B. The git checkout-index command exports everything from the
working directory that is in the index or committed, but it will
ignore local changes in the working directory that haven't been
"added".  So use "git add" or "git commit" judiciously before running
this script to get all local changes relevant to website generation
tested by this script.

To build the local form of the website (including both the doxygen and
DocBook forms of our documentation) 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 (but with stdin configured as below using echo).
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 doxygen and DocBook
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) ran this
script as follows:

echo irwin$'\n'irwin$'\n'raven$'\n'/home/irwin/public_html/plplot$'\n'yes |scripts/generate_website.sh

==>

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 store various websites).  The above command took ~2 minutes to run
on my computer.  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

The above location translates to the following URL
<http://raven/~irwin/plplot/htdocs>, and I test that URL by clicking on most links,
checking the documentation looks good, checking the examples are
complete and look good and the source code for each language for
examples is accessible, etc.  Some iterations with the
steps above entitled

"Prepare and test the documentation" and
"Update website-related files"

will likely be required.

N.B. As explained above scripts/generate_website.sh uses the index of
the git working directory (but ignores local changes which have not
yet been added to the index) as the source tree for generating the
local website.  So there is no need to commit every documentation,
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.

N.B. The iterated result should be identical to the final result (see
below) except for correcting (if necessary) the RELEASE_DATE as mentioned
above.
_________________________________________________________________________

** Update this file (README.Release_Manager_CookBook)

Edit this file to reflect latest practices by the release manager and
also to update the many version numbers in it to the latest version
value.

_________________________________________________________________________

** Create (a preliminary version of) the release tarball and check the
   result for errors

This step depends on the steps above entitled

"Prepare and test documentation"
"Check and potentially fix internal consistency"

The -c option runs ctest on the directory tree unpacked from the
release tarball, and the -i option installs a build from that
directory tree.  N.B. be careful what you specify for the
-i option since that directory will be completely removed
initially.

scripts/make_tarball.sh -c -i /tmp/plplot_install

This script takes roughly 8 minutes to complete on my computer.

Check for errors....

find /tmp/plplot-dist-prep -name "*.out" |xargs grep -i error

If the above find command discovers any errors, then those errors
need to be fixed and this step needs to be repeated.

Browse the following install locations that were generated from the
tarball:

/tmp/plplot_install/share/doc/plplot/html/index.html
/tmp/plplot_install/share/doc/plplot/plplot-5.11.0.pdf

Look at tarball contents to make sure included filenames are
what is intended.

less /tmp/plplot-dist-prep/plplot-5.11.0.tar.gz

Look at a few man pages that were generated from the tarball, e.g.,

man -M/tmp/plplot_install/share/man pllegend
man -M/tmp/plplot_install/share/man plsurf3dl

Look at the info pages that were generated from the tarball using

info /tmp/plplot_install/share/info/plplotdoc.info
_________________________________________________________________________

** Do comprehensive test of PLplot

This step depends on the steps above entitled

"Check and potentially fix internal consistency"
"Update date/versions"

Do a comprehensive test of the interactive and noninteractive
results.

scripts/comprehensive_test.sh --do_ctest no --do_test_noninteractive no
find ../comprehensive_test_disposeable -name "*.out" |grep -v a.out |xargs grep -i error
scripts/comprehensive_test.sh  --do_test_interactive no
find ../comprehensive_test_disposeable -name "*.out" |grep -v a.out |xargs grep -i error

Alternatively, on platforms (such as MinGW/MSYS) with
limited system libraries or platforms (such as CentOS) with system libraries which are too old for
PLplot's needs you can also do comprehensive testing using epa_build
(see cmake/epa_build/README for details).

Enter results of these and all other tests at
<https://sourceforge.net/p/plplot/wiki/Testing_PLplot/#Testing%20Reports>
(which is referred to by README.release).
_________________________________________________________________________

Install and test a local copy of the PLplot website

This step depends on the step above entitled
"Install and test a
(preliminary) local copy of the PLplot website"

Follow the exact instructions given in that step except this time correct
RELEASE_DATE (configured in doc/docbook/src/CMakeLists.text) if
necessary.  Here is the command I used for this step

echo irwin$'\n'irwin$'\n'raven$'\n'/home/irwin/public_html/plplot$'\n'yes | scripts/generate_website.sh
_________________________________________________________________________

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 --no-p --no-g --chmod=ugo=rwX \
/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.

The --no-p --no-g --chmod=ugo=rwX options were introduced recently and
are recommended by the rsync man page to preserve SourceForge's file
and directory attributes.  It is only with those options that I am
able to get a clean result for a second rsync run.  (Otherwise, each
directory is mentioned as being changed.)  These options may solve the
website permissions problem mentioned in an Appendix.

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 godsend since it tells you exactly what
will happen without actually doing it.

Once you have a proper upload of the local website to SourceForge, test
it as before.  Also, click the xhtml and css validate buttons on each of
index.php, download.php, examples.php, documentation.php, and credits.php
to validate those pages.

_________________________________________________________________________

** Create ChangeLog.release

N.B. commit all local changes to the repository so they will be
reflected in the ChangeLog, tagged version of the release, and the
release tarball.  And if there are committed changes after this one
repeat this step so the ChangeLog.release commit is the last commit on
master for this release cycle (with the possible exception of the
current file, README.Release_Manager_Cookbook).

Prepare the ChangeLog.release file to keep track of all changes
made for the release.  Make sure master is up to date using

git fetch
git log -1 origin/master
git log -1 master

Create final ChangeLog for this release

# maint is a private topic branch I use for maintenance.
git checkout maint
git log --name-status <commit_id>..master >| ChangeLog.release

where <commit_id> is the last commit id of the log of commits for the
previous release cycle (i.e., d4fdf0bab for the 5.10.0 release).  Note
this result (unlike the prelimary version above) will be in the
traditional reverse chronological order.

# Commit, fast-forward merge to master, and push

git commit -all
git checkout master
#Last check there is nothing to download from server.
git fetch 
# Only if git fetch did not download anything....
git merge --ff-only maint
git push origin master

The above command destroys the ChangeLog.release file
from the previous release and the associated commit on
master (and origin/master) should be the last commit of
this release.
_________________________________________________________________________

** Create the PLplot Release

   ++ Preliminaries

The preliminaries are very simple with git.  Stay on master and
change nothing there for the following tests of this release.


   ++ Create a final release tarball and check the result for errors

Follow the above step entitled 

"Create (a preliminary version of) the release tarball and check the result for errors"

but this time for the current last commit of master (which includes
the latest ChangeLog.release) to make sure the
tarball is exactly consistent with the release tag that will be
created for that commit (if all is well).


   ++ Tag the release

Assuming all is well with the release tarball tests, then tag HEAD of master
and push it.

git checkout master
git tag plplot-5.11.0
# Irrevocable step since no pushed tags can ever be deleted.
git push --tags

(Note we are changing release tag names here from the old scheme
which would have been v5_11_0 to a more informative scheme for names.)

   ++ Sign the release with your plplot Release Manager gpg key

gpg --default-key YYYYYYYY --detach-sign --armor /tmp/plplot-dist-prep/plplot-X.Y.Z.tar.gz

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

   ++ Verify the release tarball signing
gpg --verify /tmp/plplot-dist-prep/plplot-X.Y.Z.tar.gz.asc

   ++ Make a SourceForge file release

#IMPORTANT
cd /tmp/plplot-dist-prep/

sftp airwin,plplot@frs.sourceforge.net
cd /home/frs/project/p/pl/plplot/plplot
mkdir 5.11.0\ Source
cd 5.11.0\ Source
put plplot-5.11.0.tar.gz.asc
put plplot-5.11.0.tar.gz
exit

Make, e.g., plplot-5.11.0.tar.gz, the "latest" version.

login to SF website
files ==> plplot ==> 5.11.0 Source ==> view details (the "i" icon) for
plplot-5.11.0.tar.gz ==> select "all" for the default

The above used to spin indefinitely with iceweasel.  Now it finishes
with a "properties updated" message, but it doesn't appear to "take"
immediately so check it later.

# Save a local copy of the release tarball for future reference and
# also check it.
cd /home/software/plplot_svn/HEAD/export #(or wherever)
cp -a /tmp/plplot-dist-prep/plplot-5.11.0.tar.gz* .
gpg --verify plplot-5.11.0.tar.gz.asc

Prepare concatanated release notes + Changelog.

cd plplot_tags_5.11.0
echo "

DETAILED CHANGELOG FOR THIS RELEASE

" | cat README.release - ChangeLog.release >| /tmp/README.release

cd /tmp
sftp airwin,plplot@frs.sourceforge.net
cd /home/frs/project/p/pl/plplot/plplot/5.11.0\ Source
put /tmp/README.release
exit

   ++ Make a SourceForge news item concerning this release

Create a news item for this release largely following previous
news items (or even identical to them but with a changed title).

Point your browser to http://sf.net/projects/plplot and login.  A
news item will then be available on the menu bar.  Click that, then
"new post".

Enter the title (e.g., PLplot Release 5.11.0) and the text.  Surround
the URL's in the text with angle brackets, e.g.
<http://sourceforge.net/projects/plplot/files/plplot>.

For now I simply make all paragraphs one giant line which seems
to give reasonable default results.

   ++ Publicize the release announcement

Jerry: macresearch.org

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

   ++ Prepare immediately for the next release cycle

  a. Preserve the historical record of the
     significant changes between versions of PLplot in one file by
     prepending README.release for 5.11.0 to OLD-README.release

cat README.release OLD-README.release > OLD-README.release_new
mv OLD-README.release_new OLD-README.release


  b. Update README.release file to reflect the start of a new release cycle.

--- Appendix ---
_________________________________________________________________________

** GNU Privacy Guard (gpg)
A brief summary of developer relevant gpg commands, see also:
http://dewinter.com/gnupg_howto/english/GPGMiniHowto.html,
man gpg, and http://www.gnupg.org/faq/GnuPG-FAQ.html.

   ++ Configure key-server (if you haven't done that already) by editing
  $HOME/.gnupg/gpg.conf.  Also specify the auto-key-retrieve option
  for convenience.

   ++ List keys on your keyring that have been retrieved or generated so far:

gpg --list-keys irwin

   ++Search for any previously published keys that you might want to
  revoke.  (Note the search phrase is case insensitive but the search
  is done on the Boolean AND of the terms so the following search would
  miss any key generated in the past by Alan Irwin because of the
  middle initial "W." that is specified for the search).  OTOH, I
  always use my middle initial for publications to reduce name clashes.

gpg --search-keys Alan W. Irwin

   ++ Create a new key:

gpg --gen-key

  With gnupg 1.4.10, I chose the following options when creating a new key:
  
Please select what kind of key you want:
  (1) RSA and RSA (default)

What keysize do you want?
2048 (default)
5-year expiration date.

....

Real name: Alan W. Irwin
Email address: airwin@users.sourceforge.net
Comment: Time Ephemerides key
You selected this USER-ID:
    "Alan W. Irwin (Time Ephemerides key) <airwin@users.sourceforge.net>"


N.B. nameofkey below is the name of the key, usually specified by the
second number after the slash for the first pub line given by
"gpg --list-keys".  For example, the above key gives the following
result:

software@raven> gpg --list-keys irwin
pub   2048R/BB159E92 2011-08-19 [expires: 2016-08-17]
uid                  Alan W. Irwin (Time Ephemerides key) <airwin@users.sourceforge.net>
sub   2048R/C5ECCF77 2011-08-19 [expires: 2016-08-17]

So the name could be BB159E92.  Other possibilities exist as well such
as "irwin", but that might not be unique.

Here is a complete recording of the gpg --edit-keys commands where I
added an additional user ID with the different comment "PLplot key" to my
existing key.  Note  this technique
could be used to add an additional user ID with a different
Real name or Email address as well.

gpg --edit-key irwin
gpg> adduid
Real name: Alan W. Irwin
Email address: airwin@users.sourceforge.net
Comment: PLplot key
Okay # to accept this added subkey
... need to enter passphrase

gpg> uid 5 # to select the new user ID for additional changes
gpg> trust # select ultimate since you ultimately trust yourself.  :-)
Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y

# Do to a gpg bug, the trust value looks like it is not updated, but
# it is so if you

gpg > save  # To save your changes, the trust value listed by

gpg --list-keys irwin

is correct.

If you make a mistake in adding a new user id.... (which happened to
me when I put down a wrong e-mail address).

gpg --edit-key irwin

adduid  (fill in correct e-mail address this time)
uid number (to select uid to work on for further commands
revuid  (revoke bad e-mail one)
primary (to make the new one the primary one, I am not sure that is necessary)
trust  (to make the new one ultimately trusted, again, not sure that is necessary.  N.B. didn't seem to change trust value, but that was just bad output)

save  (to get out again)

When edited the next time showed ultimate trust value for correct id, but
I don't know whether that was the above primary/trust subcommands or
whether those were necessary at all.  It turned out those were not
necessary at all as I later used the above sequence to generate
a libLASi key and a FreeEOS uid key.

   ++ Generate a revocation certificate.  Note this requires the pass phrase
  specified at the time of key generation so keep that pass phrase in
  a safe place or else generate the revocation certificate right after
  generating the key, and keep that certificate in a safe place.  I chose
  the former course (keep the pass phrase safe).  N.B. the options should
  appear below in the order given!

gpg --armor -o nameofkey-revocation.asc --gen-revoke nameofkey

   ++ Publicly revoke old key (from FAQ):

gpg --import old-revocation.asc
gpg --send-keys nameofkey

   ++ 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 nameofkey

gpg --refresh-keys  (to update from the server all keys including your own).

This verified that the bad irwin address was revoked even though
gpg --search-keys Alan W. Irwin

still shows revoked uid as the #1 uid.
_________________________________________________________________________

** 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.  The default configuration appears
to give good results.  You can check those results by the ntpq -pe command,
e.g.,

software@raven> ntpq -dp
1 packets reassembled into response
     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
2 packets reassembled into response
 one.tariox.com  24.150.241.178   2 u   7d 1024    0   79.179   -6.028   0.000
2 packets reassembled into response
 tor-web-02.surr 97.107.129.217   3 u  33d 1024    0   79.696   -4.199   0.000
2 packets reassembled into response
*helliana.com    128.9.176.30     2 u  580 1024  177   82.416    0.120   0.518
2 packets reassembled into response
 chelsea.ii1.net 216.218.254.202  2 u  16d 1024    0   33.252    5.646   0.000

The delay column is the round-trip travel time (in ms) to the indicated server.

The offset column is the "combined time offset" (in ms) for the
indicated server.  I assume this is the offset of that server clock from
the weighted mean of all the clocks.

The jitter column is the "exponentially-weighted rms average" for the
indicated server.  I assume it is in ms so the above jitters of 0.000
show a very small rms for those servers, i.e., a clock of extremely
high quality.
_________________________________________________________________________

** System prerequisites for viewing local website

You should install both apache and PHP on your computer.  For Debian stable
(a.k.a. wheezy) 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.

After the above changes, you must restart the apache server.  On
Debian this is done with

service apache2 restart

(When user directories are enabled this way, for the above case
where

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

that directory location browses as
http://raven/~irwin/plplot/htdocs/.)
_________________________________________________________________________

Fix website permissions

When the release manager uploads the website, those files belong to both
him and the PLplot group.  So in theory those files can be overwritten by
anyone else belonging to the group.  But in the past, this did not work
and whenever someone else tried to upload the website (e.g., when the
release manager changed), there were lots of permission issues to deal with.

This discussion of dealing with permissions problems may be moot now
because of the--no-p --no-g --chmod=ugo=rwX options recently
introduced for the rsync command above or because Allura handles website
file permissions differently now.  But we won't know that for a
fact until someone besides the current release manager attempts to
generate the website and upload it so I will leave the following
instructions for dealing with permissions problems in place, "just in
case".

Note that when changing those who upload the website, the SF
permissions (at least in the pre-Allura version of SF) were not set
up correctly to delete files belonging to the old release manager
using rsync.

If this problem re-occurs, then one thing to try is to attempt to
mass-delete all website files using

mkdir /tmp/empty
rsync -av --delete  /tmp/empty/ airwin,plplot@web.sourceforge.net:htdocs

followed by the original rsync command above to upload the website using
the new ownership of files.  

For more on the extremly non-posix permissions of the SF website files
see
<https://sourceforge.net/p/forge/documentation/Project%20Web%20Filesystem%20Permissions/>
which claims, for example, that any authorized PLplot user can delete
files regardless of ownership so the above may work fine.  But that document also implies you
can change permissions from the defaults which (as reported by the
sftp "ls -l" command) are "drwxrwxr-x" for all directories and
"-rw-rw-r--" for all files.  This is indeed true using the sftp
"chmod" command which allows you to change permissions one file at a
time (ugh).  But any attempt to get rsync to change permissions from
these defaults (e.g., with the "--no-g
--chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=r" set of options with or without
-no-p and starting from empty or not) failed.

"Just in case" the above mass-deletion with rsync fails, this quite
laborious method worked to delete all files in the past.

sftp airwin,plplot@web.sourceforge.net

Then use the 

ls -l

command to figure out who owns what and the

rm *

command on the _file_ contents of each subdirectory of htdocs, and use
the

rmdir <directory name>

command on empty directories.

Note, sftp has no recursive feature so you have to figure out the
directory structure and cd to the correct directory levels to remove
the files in each directory, ugh.  I did try the sftp chown command,
but that did not work so the only possibility I could find was the above
commands to remove htdocs and everything below it in a piece-meal fashion.
_________________________________________________________________________
