Configuration of these instructions. export plplot_version=5.13.0 export old_plplot_version=5.12.0 This configuration is obviously real for the command-line commands below that use these environment variables, but only symbolic for the few cases below where a GUI is used. INDEX ** Prepare a (preliminary) version of the ChangeLog file for this release ** Prepare the README.release file and/or encourage those who have made changes in this release cycle to update that file ** Update versions ** 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). _________________________________________________________________________ ** Prepare a (preliminary) version of the ChangeLog file for this release This step does not depend on other steps. Confirm previous release tag. git tag --list |grep "^plplot-${old_plplot_version}" Checkout an up-to-date master branch, then create the preliminary ChangeLog from that. git checkout master git log --name-status --reverse plplot-${old_plplot_version}..HEAD >| /tmp/ChangeLog.release_preliminary Also, create a summary of all the commits topics for quick reference. git log --oneline --reverse plplot-${old_plplot_version}..HEAD >| /tmp/ChangeLog.release_preliminary_summary This file is useful for counting commits for this release cycle. Note because of the --reverse option above the order of these logs will be in chronological order. But it is traditional for the final version ChangeLog 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 encourage 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". Skim /tmp/ChangeLog.release_preliminary to make sure README.release is complete with regards to all major developments during this release cycle including and especially all API changes. _________________________________________________________________________ ** Update versions This step depends on the step above entitled "Prepare the README.release file ..." Update PLplot version in www/examples.php. Also follow the instructions in cmake/modules/plplot_version.cmake to update all version information. _________________________________________________________________________ ** 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 encourage 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 your best estimate of the UTC release date which is specified as RELEASE_DATE in doc/docbook/src/CMakeLists.txt. That value might need further revision when generating the the final website result below. 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_fortran_parameters ... check_ifort_definitions_file ... check_libtclmatrix_capabilities ... check_plplot_h.inc ... check_plplotcapi_defines ... check_swig_documentation ... check_tcl_parameters The check_api_xml_consistency target currently (5.13.0) fails so that target has been excluded from the dependencies of check_all. Note the check_api_xml_consistency target only exists if -DADD_SPECIAL_CONSISTENCY_CHECKING=ON and our build system finds the golang application "plplot-doc-check" which has been developed by Hǎiliàng Wang and which is executed by that check_api_xml_consistency target. For more details concerning how to build and install "plplot-doc-check see the commentary in doc/docbook/src/CMakeLists.txt. Currently (5.13.0), plplot-doc-check (and therefore the check_api_xml_consistency target) finds two inconsistencies which are: c_plshade1 is not documented. para 0 of func plGetCursor type mismatch [ PLGraphicsIn * ] vs. [ struct PLGraphicsIn * ] The first inconsistency is expected (plshade1 is C only so it is not part of the common API, and my plan is to deprecate it for our next release. This issue will be resolved when c_plshade1 is removed from our source tree, but it must go through a deprecation period first. The second api_xml inconsistency has no immediately obvious cause and is likely due to the old version of golang that I have installed on Debian Jessie since Hǎiliàng Wang does not confirm this issue for his latest version of golang. Note the above check_plplot_h.inc target 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, configure PLplot with the -DADD_SPECIAL_CONSISTENCY_CHECKING=ON option and build each of the above targets (except for check_api_xml_consistency) by building 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 (except for check_api_xml_consistency should run with no cmp or other errors/warnings at all, e.g., software@raven> make check_all should "just work" without errors. Then (as of plplot-5.13.0) finish up such checking by building the check_api_xml_consistency target which should reveal the known c_plshade1 issue above and possibly (depending on what golang version you have) the second plGetCursor "issue". _________________________________________________________________________ ** Update website-related files This step does not depend on other steps. Look for any fundamental standard examples changes using git diff --ignore-all-space plplot-$old_plplot_version -- examples/lua (I chose examples/lua here rather than examples/c since the lua examples are normally kept right up to date with any fundamental changes in the C examples, but without the churn that sometimes occurs in examples/c.) If the above test shows there is a necessity to update the examples list in scripts/htdocs-gen_plot-examples.sh, then do that. 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. For example, 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" 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 ~3 minutes to run on my computer. You can check for warnings by find /tmp/plplotdoc -name '*.out' |xargs grep -i warning |less This turned up quite a few warnings including 3 from doxygen, but all of these warnings seemed ignorable. 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 |grep -vE 'unable to read file loc from' (That grep -vE stanza is to remove output lines from doxygen that tend to include some case variants of "error" in the string because the referred to function name contains that substring.) The above location translates to the following URL , 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 ~10 minutes to complete on my computer. Check for warnings. find /tmp/plplot-dist-prep -name "*.out" |xargs grep -i warning |less Those appear to be fairly numerous, but in all cases expected such as known cmake warnings, known doxygen warnings due to its poor code parsing ability, etc. find /tmp/plplot-dist-prep -name "*.out" |xargs grep -i error |grep -Ev 'unable to read file loc' (The last stanza is to remove some spurious doxygen warnings for the Debian Jessie version of doxygen). This search found some hits, but all seem to be innocuous except possibly for the following doxygen error /tmp/plplot-dist-prep/build_dir/make_prebuild_dist.out:error: NamespaceDef::insertMembers(): member `_swig_property' with class scope `' inserted in namespace scope `plplotc'! /tmp/plplot-dist-prep/build_dir/make_prebuild_dist.out:error: NamespaceDef::insertMembers(): member `_swig_property' with class scope `' inserted in namespace scope `plplotc_fixed'! (I count this as one error because those two python files are duplicates of each other.) However, I can find no issues with the doxygen-produced documentation of plplotc.py (and plplotc_fixed.py). So I attribute this error to some issue with doxygen parsing of python. Look at the ctest results: less /tmp/plplot-dist-prep/ctest_build_dir/ctest.out less /tmp/plplot-dist-prep/ctest_build_dir/Testing/Temporary/LastTest.log 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/doxygen/html/index.html /tmp/plplot_install/share/doc/plplot/plplot-$plplot_version.pdf Look at tarball contents to make sure included filenames are what is intended. less /tmp/plplot-dist-prep/plplot-$plplot_version.tar.gz Also compare the table of contents of that tarball for the previous release with the present release. tar ztf ../export/plplot-$old_plplot_version.tar.gz |sort >| /tmp/${old_plplot_version}.out tar ztf /tmp/plplot-dist-prep/plplot-$plplot_version.tar.gz |sed -e "s?${plplot_version}?${old_plplot_version}?g" |sort >| /tmp/${plplot_version}.out diff -au /tmp/${old_plplot_version}.out /tmp/${plplot_version}.out 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 the following comprehensive test (and check of that test) twice, once for the minimum CMake version and once for the latest CMake version to check our build system works fine for this range of CMake versions consistent with the remarks in README.release. (Note is is assumed here that the cmake version was determined by manipulating the PATH, but you can also specify the cmake version explicitly by using the "--cmake_command" option for the comprehensive test script.) Run (from a source tree with a space in the prefix) scripts/comprehensive_test.sh --prefix "../comprehensive_test_disposeable blank" --do_submit_dashboard yes) (Note because of the choice of a "spaced" source tree and --prefix, this test has a space in the prefixes of the source, build, and install trees.) Check the results: # Check for any regressions in the warnings in the cmake output. less ../comprehensive_test_disposeable\ blank/shared/noninteractive/output_tree/cmake.out # Check for some non-standard warnings: grep -i warning ../comprehensive_test_disposeable\ blank/*/*/output_tree/*.out |grep -vE 'cmake.out|ctest.out' |grep -vE 'PLPLOT WARNING|PRIVATE|deprecated|Resource leak|2 problems|Some graphical or stdout' # Check for all errors: grep -i error ../comprehensive_test_disposeable\ blank/*/*/output_tree/*.out # Check for any ldd issues for the shared and nondynamic cases. grep -iE 'found|symbol|undefined' ../comprehensive_test_disposeable\ blank/*/*/output_tree/*ldd.out # Check for any PostScript or Text differences between all non-C languages and the corresponding # C results. grep -B1 -A3 "Missing examples" ../comprehensive_test_disposeable\ blank/*/*/output_tree/*.out |less These checks showed no issues other than long-standing PostScript differences for ocaml (and therefore no PostScript difference regressions) in the ctest results. In addition, 3 dashboards (for the shared, nondynamic, and static cases) were correctly posted to although with long-standing spurious warning counts for the cmake step which I have been unable to figure out, yet. Enter results of these and all other tests at (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 and update ChangeLog.cumulated_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 and maint are up to date using git fetch git log --oneline -1 origin/master git log --oneline -1 master git log --oneline -1 maint Create final ChangeLog for this release # maint is a private topic branch I use for maintenance which I keep # identical to master (confirmed with above git log command) before I # start using it. git checkout maint git log --name-status ..master >| ChangeLog.release where is the last commit id of the log of commits for the previous release cycle (i.e., plplot-$old_plplot_version for the $plplot_version release). Note this result (unlike the prelimary version above) will be in the traditional reverse chronological order. Preserve the historical record of the significant changes between versions of PLplot in one file by prepending README.release for $plplot_version to README.cumulated_release cat README.release README.cumulated_release > README.cumulated_release_new mv README.cumulated_release_new README.cumulated_release # Commit, fast-forward merge to master, and push git add ChangeLog.release git commit # There is a chicken/egg situation here since the ChangeLog.release file # does not include the log of its own last commit. You could address # that issue by re-running the above commit command, and amending the commit. # However, that amending will change the commit id so the ChangeLog.release # will have incorrect information about its own commmit id. # So the best course is not to do such amending and accept that the # ChangeLog.release file will not include the log of the last commit (i.e., its own commit) # for the release. 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 (with signed key) HEAD of master and push it. git checkout master A list of your GPG keys can be obtained using, e.g., software@raven> gpg --list-keys Alan pub 2048R/BB159E92 2011-08-19 [expires: 2021-12-12] uid Alan W. Irwin (Time Ephemerides key) uid Alan W. Irwin (libLASi key) uid Alan W. Irwin (FreeEOS key) uid Alan W. Irwin (PLplot key) The BB159E92 field above is the key one. git tag --local-user=BB159E92 --message="PLplot ${plplot_version} release" plplot-${plplot_version} # Note, a tag simply tags a particular commit so if I checkout some # other branch (such as maint) that has the same tagged commit as # as master, then the "git tag --list" command will find the tag # (which I proved was actually true for maint). # Verify signature (which also confirms the above tag message) git tag --verify plplot-${plplot_version} # Irrevocable step since no pushed tags can ever be deleted from # upstream repository. git push origin plplot-${plplot_version} (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 BB159E92 --detach-sign --armor /tmp/plplot-dist-prep/plplot-$plplot_version.tar.gz where BB159E92 refers to the public key for Alan W. Irwin as taken from the above key list. ++ Verify the release tarball signing gpg --verify /tmp/plplot-dist-prep/plplot-$plplot_version.tar.gz.asc ++ Make a SourceForge file release #IMPORTANT cd /tmp/plplot-dist-prep/ sftp airwin,plplot@frs.sourceforge.net <| /tmp/README.release cd /tmp sftp airwin,plplot@frs.sourceforge.net < plplot ==> ${plplot_version} Source ==> view details (the "i" icon) for plplot-${plplot_version}.tar.gz and hit the "select all" button and "save" button It finishes with a "file properties updated" message, and appears to "take" immediately. Note also, the above does not work with konqueror because enabling ".sourceforge.net" under javascript does not appear to cover all the javascript stuff that the sourceforge site users. (firefox accepts javascript from any source so does not have this problem, but is insecure as a result). ++ 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 $plplot_version) and the text. The text is in markdown format so copying and pasting from a previous news item (using the ctrl-c command on the editing area of the old release notes to copy and ctrl-v command on the new release notes editing area since normal cutting and pasting no longer works) is a very efficient way to create the new news item. After that copy and paste, remember to change all occurrences of $old_plplot_version to $plplot_version within the text, and also to update the highlights area (by copying from the list of "2. Improvements relative to the previous release) in README.release and changing all the numbers to "*"). ++ Publicize the release announcement Jerry: macresearch.org Barbara Irwin: linuxtoday.com, lwn.net, lxer.com ++ Prepare immediately for the next release cycle a. Commit last-minute tweaks (e.g., in README.Release_Manager_Cookbook) that did not make it into the official tarball of the release or official tag of the 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. N.B. According to the recommended keyserver (which really refers to a large pool of them that are deemed reliable at any given time) is hkp://pool.sks-keyservers.net so that is what I have been using recently, and it appears so far to be reliable. ++ 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) " 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) 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 # Due 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 first sequence without trust subcommand to generate a libLASi uid key and a FreeEOS uid key. ++ Key Expiration: What to do when your key expires and you feel it is _not_ compromised in any way. (See for discussion of this method): gpg --edit-key irwin # To bump expiration date of existing key. gpg asked some reasonable # questions here such as how long until the next expiry (I specified # 5y for 5 more years). Then it asks you to verify that new expiry, # then asks for your pass phrase and then shows the changed result. gpg> expire # Save results in your local keyring gpg> save N.B. The key ID (BB159E92 in my case) remains unchanged. Publish those changed results to a keyserver (which propagates them to all other key servers). gpg --send-keys key ID where key ID is BB159E92 for my case. ++ Verify the above propagated. Use a different user account with keyring that has not been locally updated. Then update it using gpg --refresh-keys Then verified that refresh worked using, e.g., gpg --list-keys irwin gpg --verify plplot-${plplot_version}.tar.gz.asc etc. ++ 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 pool so that others can obtain it to verify your signature on the release tarball. gpg --send-keys key ID where key ID is BB159E92 for my case. gpg --refresh-keys to update from the key server pool all keys on your keyring 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 Jessie 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 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 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. _________________________________________________________________________