diff --git a/admin_doc/source/client_release.rst b/admin_doc/source/client_release.rst index d8d7eef7faf08862aea7020c2895142373e27276..31a2d29c434362036c5f6c8e49ce63f4d32c01ab 100644 --- a/admin_doc/source/client_release.rst +++ b/admin_doc/source/client_release.rst @@ -2,8 +2,192 @@ Preparing a new client release ================================ -Disclaimer -========== +.. NOTE:: + The steps here are only suggestions. You will undoubtedly discover better + and/or different ways to go about this. + +Develop +======= + +Implement the features and bug fixes you wish to include in the new +client release. It's easiest to do this within a virtual environment on +your workstation. That way you can make changes to the code and then:: + + cd gracedb-client + python setup.py install + +which will install into your virtual environment. When you are satisfied +with the changes, commit and push. + +.. NOTE:: + It's a good idea to test this version on Scientific Linux and Debian + at the clusters before proceeding. + The versions of Python there may be a bit behind the one on your workstation, + and that can cause complications. I've been burned by this before. + You can do it by cloning the ``gracedb-client`` package on a cluster + headnode and building in a virtual environment as show above. + +Changes for packaging +===================== + +Update the source code for the new version number, and update the changelog. +Here are the files you will need to change: + +* ``setup.py``: bump the version number +* ``debian/changelog``: list your changes in the prescribed format +* ``ligo-gracedb.spec``: check version, unmangled version, and release number +* ``ligo/gracedb/__init__.py``: update ``GIT_TAG`` +* ``ligo/gracedb/cli.py``: update ``GIT_TAG`` +* ``ligo/gracedb/test/test.py``: update the version number in the ``GIT_TAG`` test + +After editing these files, make sure to commit and push. Also make sure the +client still passes the unit tests:: + + python setup.py install + cd gracedb-client/ligo/gracedb/test + unset TEST_SERVICE + python test.py + +Tag this version of the repo and push the tag:: + + git tag --list + git tag -a YOUR_GIT_TAG + git push --tags + +.. NOTE:: + Git tags look like this: ``gracedb-1.20-1``, where 1.20 is the version and + the last number corresponds to the build number (here, 1). + +Prepare to upload to PyPI +========================= + +Clear everything out of the directory ``gracedb-client/dist`` and then +build the source tarball:: + + python setup.py sdist + +Log into ``testpypi.python.org`` and change the version number. Click on the package +name in the right-hand menu, then click 'edit' near the top. Bump the version +number as appropriate, and then click 'Add Information' at the bottom. + +Upload the package to the test PyPI instance. This is easier if you install +the python package ``twine``. I tend to do this in a special virtual environment +used only for this purpose:: + + deactivate + cd + cd my_virtual_envs + virtualenv --system-site-packages pypi-upload + source pypi-upload/bin/activate + pip install twine + + cd /path/to/gracedb-client + twine upload dist/*.gz -r test + +Make sure that you can install and use the package from the test PyPI:: + + deactivate + cd + cd my_virtual_envs + virtualenv --system-site-packages test + source test/bin/activate + pip install -i https://testpypi.python.org/pypi ligo-gracedb --upgrade + + cd /path/to/gracedb-client + git pull + cd ligo/gracedb/test + python test.py + cd ~/my_virtual_envs + deactivate + rm -f -r test + +Log into ``pypi.python.org`` (the non-test instance) and update the version number +as you did above for the test instance. Next, upload the package to the +regular, non-test PyPI:: + + deactivate + cd ~/my_virtual_envs + source pypi-upload/bin/activate + cd /path/to/gracedb-client + twine upload dist/*.gz + +Lastly, make sure you can pip install the package:: + + deactivate + cd ~/my_virtual_envs + virtualenv --system-site-packages test + source test/bin/activate + pip install ligo-gracedb + deactivate + rm -f -r test + +Steps for LIGO packaging +======================== + +Move the source tarball to ``software.ligo.org``. I do this with a script +I obtained from Adam Mercer, ``lscsrc_new_file.sh``. I have added a version +of this to the GraceDB ``admin-tools`` repo:: + + cd /path/to/gracedb-client/dist + cp /path/to/admin-tools/releases/lscsrc_new_file.sh . + ./lscsrc_new_file.sh ligo-gracedb-*gz + +.. NOTE:: + You must run the script in the same directory where the tarball lives. + Otherwise it will put it onto the server in a weird subdirectory rather + than just the file. + +Make sure that the file is accessible in the expected location, something +like ``http://software.ligo.org/lscsoft/source/ligo-gracedb-1.20.tar.gz``. + +Send an email to the packagers notifying them of the new package. You will +probably want to include the information that you put into the changelog. +Here's an example of one that I sent:: + + to daswg+announce@ligo.org + + There is a new release of the GraceDB client tools. + + New features are: + Improved error handling for expired or missing credentials + Improved error handling when server returns non-JSON response + Added --use-basic-auth option to command-line client + + + The release tag is: ligo-lvalert-1.20-1 + + The source is available at: + + http://software.ligo.org/lscsoft/source/ligo-gracedb-1.20.tar.gz + + thanks! + Branson + +After the package is in the testing repo, look for the corresponding row in the +`SCCB wiki <https://wiki.ligo.org/SCCB/WebHome>`__. +One of the packagers will hopefully have added it. + +Once the new package is installed at the system level on the bleeding-edge +head nodes, test it on different OSes (probably ``ldas-pcdev4`` at CIT for +Scientific Linux and ``atlas9`` at AEI for Debian). + +Update the SCCB wiki entry stating that the package has been tested on SL +and Debian and request that it be moved into production. + +Forward the package announcement email to the SCCB with some additional text +notifying them that the package is waiting for their approval. Here is an +example of one that I sent:: + + to daswg+SCCB@ligo.org + + dear SCCB, + + I have tested this release on ldas-pcdev4 @ CIT and atlas9 @ AEI. The + release passes the unit tests, so I am requesting that it be moved + into production. + + best, + Branson + + -The steps here are only suggestions. You will undoubtedly discover better -and/or different ways to go about this.