Abjad packaging checklist:

 1. Open abjad/etc/packaging_transcript.txt and create a new entry.
    Record the date of packaging in the packaging transcript.
    Record the revision of repository in the packaging transcript.

 2.  Document the packaging environment in the packaging transcript.
    (a) Apply any OS updates to the machine on which you will produce the package.
        Record the output of "uname -v" in the packaging transcript.

    (b) Decide whether to upgrade svn.
        OS X svn binaries are available at http://subversion.apache.org/packages.html#osx.
        The openCollabNet universal build maintained by Jeremy Whitlock is recomended.
        Regardless of whether svn is upgraded or not, record the output of "svn --version".

    (c) If necessary, upgrade Python on the packaging machine.
        Python upgrade procedures are OS-dependent.
        Record the output of "python --version" in the packaging transcript.

    (d) Update pip with "sudo pip install --upgrade pip".
        Record the output of "pip --version" in the packaging transcript.

    (e) Update py.test with "sudo pip install --upgrade pytest".
        Record the output "py.test --version" in the packaging transcript.

    (f) Update Sphinx with "sudo pip install --upgrade Sphinx".
        Record the output of "sphinx-build --version" in the packaging transcript.

    (g) Update LilyPond.
        Record the output of "lilypond --version" in the packaging transcript.

    (h) Update ImageMagick.
        Record the output of "convert --version" in the packaging transcript.
    
    (i) Update Graphiz. Go to www.graphviz.org.
        Record the output of "dot -V" in the packaging transcript.


 3. Author release notes:
        Open doc/source/start_here/versions/index.rst.
        Add a sentence giving the release date and repository revision number.
        Example: "Released 2009-05-21. Built from r5752."
        Run "ajv count tools ." and "scr/devel/count-source-lines".
        Add a sentence detailing the output of these scripts to this chapter.
        Example: "Implements 405 public classes and 1066 functions totalling 182,000 lines of code."
        Run "svn log --limit 30 | less" (or 40 or whatever) and read output.
        Or run "svn log --revision 4083:4977 | less" and read output in chronological order.
        Read log and write release notes.
        Follow the pattern already established in the document.
        List new features and functionality.
        Highlight significant new functionality with a musical example.
        Begin entries with an active verb in the simple past.
        Order entries by leading verb.
        List adds first and extensions second.
        List changes in user syntax last.
    Also update change log:
        Open docs/source/appendices/change_log/index.rst 
        Add entries for function, method and class names changed during development.

 4. Commit.

 5. Change to the abjad root directory, then to ly/ly and run `make all`.
    This will update the parser's LilyPond environment scrape to the current
    version of LilyPond in use in the packaging environment.
    If any part of the scrape fails to compile, fix, commit and repeat this
    step.

 6. Change to the abjad root directory.
    Run "ajv clean .".
    Then run "py.test".
    If any tests break, fix, commit and repeat this step.
    Record mainline py.test test results in the packaging transcript.

 7. Change back to the abjad root directory and run "ajv api -M".
    You will need Graphviz installed to build the API.
    OS X Graphviz downloads are available at http://www.graphviz.org/Download..php.
    Ubuntu Graphic installation is available with "sudo apt-get install graphviz".
    The HTML version of the API should build with no warnings and no errors.
    If Sphinx gives any warnings or errors, fix, commit and go back to (6.)

 8. Change to abjad/tools.
    Run "ajv doctest".
    If any tests break, fix, commit and go back to (6.).
    Record mainline doctest test results in the packaging transcript.

 9. Change to the experimental directory.
    Run "ajv clean .".
    Then run "py.test".
    If any tests break, fix, commit and go back to (6.).
    Record experimental py.test results in the packaging transcript.

10. Stay in the experimental directory.
    Run "ajv doctest".
    If any tests break, fix, commit and go back to (6.).
    Record experimental doctest test results in the packaging transcript.

11. Return to the mainline.
    Start the Abjad interpreter to run one final sanity check.
    Run 'show(Note("c4"))'.
    Then call iotools.ly(), iotools.log(), iotools.pdf() and iotools.redo().
    Then run 'play(Note("c4"))'.
    If any test fails, fix, commit and go back to (6.)
    Record sanity check test results in the packaging transcript.

12. Change to the abjad/etc/optimization directory.
    Create a v2.x optimization transcript by copying the most recent such file.
    Record memory usage and profiling test results in the optimization transcript.

13. Run "svn info".
    Note the current revision of the working copy you are packaging.
    Open docs/source/start_here/versions/index.rst again.
    Check the release date indicated there.
    Check the revision number indicated there.
    Make sure the revision number equals current revision + 1.

14. Change to abjad/docs.
    Run 'make clean'.
    This step is important because failing to 'make clean' before building
    the docs can cause the doc tarball made below to exceed 25 megs.
    PyPI rejects doc tarballs greater than 25 megs.

15. Change to experimental/docs.
    Run "make clean".
    Run "avj api -X". If any erros occur, fix, commit and go back to (6.)
    Record experimental build results in the packaging transcript.

16. Change back to abjad/docs.
    Run "ajv api -M". If any errors occur, fix, commit and go back to (6.)
    Record HTML build results in the packaging transcript.

17. Run "make latex". 
    If any errors occur, fix, commit and go back to (6.)
    Record the LaTeX build results in the packaging transcript.

18. Run "make latexpdf". 
    If any errors occur, fix, commit and go back to (6.)
    Open the docs/build/latex/Abjad.pdf file that results.
    Click around some to make sure everything looks OK.
    Record Abjad.pdf build results in the packaging transcript.
    Open the docs/build/latex/AbjadAPI.pdf file that also results.
    Click around some to make sure everything looks OK.
    Record AbjadAPI.pdf build results in the packaging transcript.

19. Copy docs/build/latex/Abjad.pdf to docs/pdf/Abjad-x-y.pdf.
    Copy docs/build/latex/AbjadAPI.pdf to docs/pdf/AbjadAPI-x-y.pdf.
    Do both of these with 'cp' and not with 'svn cp'.

20. Add docs/pdf/Abajd-x-y.pdf to svn.
    Add docs/pdf/AbjadAPI-x-y.pdf to svn.

21. Remove docs/pdf/Abjad-x-(y-1).pdf from svn.
    Remove docs/pdf/AbjadAPI-x-(y-1).pdf from svn.

22. Commit.
    All tests have now passed in the packaging environment.
    All documentation has now built in the packaging environment.

23. For each additional test environment, repeat the following steps:
    [2] documenting the test environment.
    [5], [6], [7] recording py.test, doctest and sanity check test results.
    [12], [13], [14] recording HTML, LaTeX & PDF build results.

24. Complete all addition platform testing.
    Close and save the packaging transcript.
    Commit.

25. Change to abjad/trunk.
    Upgrade setuptools with "sudo pip install --upgrade setuptools".

26. Open setup.py and increment the version string found there.

27. Run 'python setup.py register sdist upload'
    Follow the login instructions provided by PyPI.
    You must have Abjad package owner credentials for this step to work.
    If you need Abjad package owner credentials, talk to Trevor, Víctor or Josiah.
    PyPI should respond with "error: None"

28. Remove 'dist' and 'Abjad.egg-info'.
    The directories are no longer needed after upload to PyPI.
    The directories should not be checked into the Abjad repository.

29. Change to docs/build/html and archive all 17 or 18 files and subdirectories therein.
    You must create a single archive of all 17 or 18 files.
    Through the Finder on the Mac you can shift-click all 17 or 18 files,
    then control-click the selected files and choose "Compress 17 items"
    from the context menu that appears.
    (Note that archiving just the docs/build/html folder will not work.)
    Name the archive Archive.zip.
    Check the size of the archive.
    The archive must be less than 25 megs.

30. Log in to The PyPI website at pypi.python.org with Abjad owner credentials.
    Talk to Trevor, Víctor or Josiah if you need Abjad owner credentials.
    Click on the Abjad link to edit PyPI's information about the package.

31. At the bottom of the "Package 'Abjad' Editing" page, click on "Choose file"
    and select docs/build/html/Archive.zip. Then click on "Upload Documentation".
    PyPI will redirect to http://packages.python.org/Abjad/.
    The newest version of the docs will appear.
    If it doesn't, debug and fix what went wrong.

32. Click your browser's "back" button to return to the "Package 'Abjad' Editing" page.
    Then click on the "edit" link to the left of the entry for the new x.y version.
    This will take you to the "Submitting package information" page.

33. Manually restore the diacritics in "Víctor Adán" and "Trevor Bača" in the "Author" field.
    (This is necessary because there's a bug in setup.py that fails on UNICODE metadata.
    So UNICODE characters must be added back in by hand on this page of the PyPI website
    rather than being more conveniently read from abjad/trunk/setup.py.)
    ("Josiah Wolf Oberholtzer" transmits fine here and doesn't have to be tweaked.)

34. Manually restore the spaces after each of the keyword phrases in
    "music composition, music notation, formalized score control, lilypond"
    in the "Keywords" field. (Again, setup.py mangles these on upload to PyPI.)

35. Click the "Add information" button at the bottom of the page to confirm.
    All PyPI editing and uploading is now complete.

36. Click around PyPI to make sure everything looks correct.
    Then leave PyPI.
    
37. Return to your Abjad sources and remove docs/build/html/Archive.zip.
    The archive should not be checked in to the Abjad repository.

38. Edit abjad/__init__.py and increment '__version__' to the *next* minor number.

39. Edit tools/configurationtools/get_abjad_version_string.py and change the
    version number string given in the docstring.

40. Commit.

41. Author release announcement and mail to abjad-user@googlegroups.com.
    Release announcement should recapitulate version history.
    
[2011-08-21, 2011-08-30, 2011-09-12, 2011-09-22, 
 2012-01-29, 2012-02-27, 2012-05-22, 2012-06-05, 2012-10-03, 2012-10-05,
 2012-10-29, 2012-12-17]
