Command line tool to wrap release scripts

[thijs]

trunk/twisted/python/_release.py now contains APIs for doing all of these things but there are no command line tools which wrap these them. These APIs mainly just invoke entrypoints of tools which do have command line interfaces, though. The xhtml and troff files are converted by invoking lore's main point. The book is a bit more complicated, since several steps are involved, and one of the tools is latex. It is not intended that users invoke these APIs, so where possible the documentation should not refer to them.

[glyph]

Let's not fall into the trap of "we don't want to suggest it to users, so let's officially not document it". The documentation should just clearly say that it is for developers, release managers, and possibly packagers.

[exarkun]

See also ReleaseAutomation.

[exarkun]

Changing summary to reflect the fact that there should only be one command line tool for doing the release, not several.

[radix]

(In [24938]) Branching to 'release-script-3439'

[radix]

Ready for review

[thijs]

1. BuildTarballsScript (and possibly other newly introduced classes and/or methods) needs an @since tag

[radix]

I suggest that @since is unnecessary for any of this code because it's in an underscore-prefixed module; it's not a public API at all so when it was introduced is not relevant.

[exarkun]

1. twisted/python/test/test_release.py
   1. genVersion should have a docstring and not include trailing whitespace
   2. StructureAssertingMixin should have a class docstring
   3. assertStructure shouldn't have trailing whitespace
   4. test_changeAllProjectVersions should have a docstring
   5. test_buildAllTarballs should have a docstring
   6. test_buildAllTarballsEnsuresCleanCheckout should have a docstring
   7. if you want, you could factor the common stuff out of test_changeVersions and test_changeVersionsWithPrerelease
   8. test_defaultChangeVersionsVersionChanger would probably be better if it called the default implementation and asserted something about its behavior
   9. same for test_defaultBuildTarballsScriptBuilder
2. twisted/python/_release.py
   1. runCommand could document what it raises or returns
   2. generateVersionFileData has some trailing whitespace
   3. DistributionBuilder class docstring could use epytext markup for blacklist @type stuff
   4. buildAllTarballs raises UncleanWorkingDirectory if passed a checkout path which doesn't exist. This isn't too big a deal right now, but it could be confusing to whoever runs the script.

The only non-trivial problem with the branch is that build-tarballs builds a sumo tarball that includes bin/admin/build-tarballs and bin/admin/change-versions. I think we wanted to avoid releasing these files?

[radix]

Thanks for the review. I've done everything you suggested save for 1.8-1.9. I also made buildAllTarballs create the destination directory when it doesn't exist: another nod to usability.

[exarkun]

Looks good. There's still one line with trailing whitespace in _release.py.

Oops. I just noticed that some of the tests fail on Windows. Here are the build results:

 http://buildbot.twistedmatrix.com/boxes-supported?branch=/branches/release-script-3439

Guess some skips need to be defined. Humm. Maybe the tests should also skip if svn or svnadmin (and whatever other external binaries the tests/code) should be skipped too.

Please fix those issues (and check the fixes on buildbot) then merge.

[exarkun]

Please take a look at the OS X failures as well. Sorry for not mentioning those before.

[radix]

(In [25225]) run commands with the default sigchld handler. refs #3439

[radix]

Ok, I've made all the tests which invoke runCommand (directly or indirectly) install the default sigchld handler for the duration of the test. Tests pass or skip on OS X, windows, and Ubuntu.

[exarkun]

The docs for DistributionBuilder.blacklist end in a typo, build instead of built.

Can you add that comment we talked about to the new scripts mentioning that they're not intended to be included in the release?

Otherwise good, please merge.

[radix]

(In [25335]) Merge release-script-3439

Author: radix Reviewer: exarkun Fixes: #3439

Two new scripts, bin/admin/build-tarballs and build/admin/change-versions, now automate most of basics of the release process. These scripts are excluded from the release itself.