[Twisted-Python] 10.1 release follow-up

[Jonathan Lange]

On Mon, Jul 5, 2010 at 1:36 PM,  <exarkun at twistedmatrix.com> wrote:
> On 08:23 am, jml at mumak.net wrote:
>>On Mon, Jul 5, 2010 at 3:08 AM,  <exarkun at twistedmatrix.com> wrote:
>>...
>>>Thanks for your work on this release, and congratulations on getting
>>>it
>>>out the door. :)
>>>
>>>I'm curious about plans to update the documentation on the website and
>>>distribute the .exe Windows installers.
>>
>>Oops, forgot to switch over the symlink for the docs. That's done now.
>
> Great, thanks!
>
> One thing that it looks like we missed again (and I'm not surprised,
> it's not well documented) is the Google Analytics doc template changes.
> This is mentioned on the APIDocs page, but maybe not described in
> sufficient detail?

I think it's not so much lacking detail as leaving gaps for
interpretation or not being step-by-step enough (which I guess is the
same thing, but a subtly different goal).

Following the documentation generation instructions was confusing for
me because:
  * originally they were incomplete and messy
  * the "api documentation" and "general documentation" steps were conflated
  * at least one of the steps required a special kind of tree, which
took me some time to figure out
  * I was using the last release and release 8.2.0 as a way of double
checking that I was doing the right thing

Things we can do now:
  * Update the current documentation so that it uses the correct template
  * Update the release process to be clearer (I think this is done
now, but I can use the previous step to double check)
  * Delete APIDocs, or at least stop recommending it -- it's easier
followed if folded in to the release doc

>>
>>I don't remember anyone saying anything about exes until now.
>
> These are mentioned on ReleaseProcess (Cut the tarballs & installers,
> 3.4), but apparently only in one of the several places where they need
> to be handled.  This is the first release where we're trying to provide
> them (#4427).
>

Ahh, ok, I see that now. I think if I'd received some sort of direct
communication about it, I wouldn't have missed them.

Other things we can do, now, to make this easier:
  * Upload the exes, re-issue the md5sum file
  * Add the exes to the Downloads page
  * Make a decision about whether we want the exes on the front page,
act on that decision
  * Update the examples in the release process doc to include the exes
  * Update the release blog post pointing to the exes

For both of these issues, a more satisfying solution would be to
automate them, putting them outside the realm of human error. However,
I think the interim steps listed above are worthwhile.

I'll do these now, and email back when I'm done.

I would greatly appreciate thoughts on the issues I raised in my original post.

jml