Front page | perl.perl5.porters |
Postings from June 2009
Re: on the perldelta (was Re: Perl 5.10.1)
Thread Previous
|
Thread Next
From:
David E. Wheeler
Date:
June 30, 2009 12:49
Subject:
Re: on the perldelta (was Re: Perl 5.10.1)
Message ID:
4DE90495-2C2C-4159-8F1C-BB318DD3F10A@kineticode.com
On Jun 30, 2009, at 12:12 PM, Nicholas Clark wrote:
> The point of the perldelta is to act as an accessible summary of the
> key
> parts of the log of changes. We're not shipping the log of changes
> as a
> changelog file, but logically I believe it's still a useful feature.
Right.
> I found that the editing attrition rate from changes to perldelta
> entries
> was "horrendous" - no more than 10% of changes became perldelta
> entries.
> Hence I think that this is one reason why moving to a policy of every
> *change* must have a perldelta entry isn't a good idea, as it won't
> solve
> anything. Either perldelta will be 10 times as big, so we might as
> well
> remove it, point people at the changelog, and tell them to skim that
> themselves, or we still have a massive editing-down problem near
> release time.
What we require for Bricolage is that all user-visible changes, bug
fixes, and significant re-organizations go into Bric::Changes. Before
a release, I edit it, and I might, for example, combine all of the
changes to documentation as shorter bullets under a top-level
"Documentation Changes" bullet. But at least the raw data is all right
there, and I don't have to go hunting through commits for it all (I'd
quit if I had to do that!).
> Secondly, currently, blead has a file pod/perl5110delta.pod. If
> changes go
> to blead, and they come with a perldelta entry, it needs to go into
> that
> file. On merging to maint-5.10, the (main) change goes where it
> should do,
> but the corresponding perldelta entry needs to move to pod/
> perl5101delta.pod
>
> Which means a custom edit, and all the git cherry-picking tools
> don't like that.
Bleh.
> We *could*, I think, "solve" this by reversing the order of the real
> file
> and the symlink, having the current, edited file always be pod/
> perldelta.pod,
> symlinked as pod/perl5110delta.pod in blead, as pod/
> perl5101delta.pod in
> maint-5.10, but for some reason I don't feel comfortable with that.
> I'm not
> sure *why*, because it's over 5 years ago now, but I do remember a bit
> feeling of progress when I changed things so that the edited file in
> version control never changed name after a release:
>
> http://perl5.git.perl.org/perl.git/commit/f6722d80bdc33aac8a78ab0f35acbb2f94ce990c
Yes, I think that makes sense.
> A comment that Tom Hukins made at work was that the perldelta is the
> revisionist history of the release, and you don't actually have a
> feel for
> what is important until later. I think he's right. If you're
> summarising
> what the most important changes are, it's much easier to do that
> later on,
> looking at the woods as a whole, rather than the trees one by one.
> For example,
> important bugs are the ones that more than one person reported, or
> you later
> realise had more ramifications than you first thought.
Yes, but having all the raw data for those 10% of changes that matter
in one file will make assembling a more useful, higher-level "changes"
document a lot easier. The important thing, I think, is to track
significant changes *as they're made*, in whatever file makes sense,
so that you don't have to trawl through 1000s of commits to find the
important bits. A file with 100s of bullets is a lot easier to deal
with than a commit log 1000s of commits long.
> Two things that should help parallelise the work.
>
> 1: I wrote "how to write a perldelta".
>
> http://perl5.git.perl.org/perl.git/blame/blead:/Porting/how_to_write_a_perldelta.pod
>
> The generation of three parts of that can be automated, if anyone
> wants to.
> First step is to make a program that generates the section, so that
> a human
> can check it, and merge it into the existing perl*delta under
> construction.
>
> [Implicit call for volunteers capable of figuring out how best to do
> this]
>
> =item New Documentation
>
> Changes which create B<new> files in F<pod/> go here.
>
> So, I think this could be automated, as follows:
>
> 1: Start with a clean exploded tarball of the previous release, and
> a clean
> checkout of the branch in question
>
> 2: Take the MANIFEST file of each
>
> 3: Search for lines matching m!^pod/.*\.pod!
>
> 4: Diff them
>
> 5: Explode if anyone deleted documentation. [No idea what the policy
> on that
> is yet]
>
> 6: For each file only in the newer MANIFEST
> a: Use git to determine its Author
> b: Open the pod file itself
> c: Grab the description section
> d: Write out a block of text starting roughly
> L<perlfoo>, by A. U. Thor, provides @description
>
> 7: Profit!
>
> [Or at least, stop and edit it manually, before committing it, or
> mailing a
> patch]
That seems pretty do-able.
> =item New Tests
>
> Changes which create B<new> files in F<t/> go here. Changes to
> existing files
> in F<t/> aren't worth summarising, although the bugs that they
> represent
> may be.
>
>
> As above.
>
> 3: Search for lines matching m!t/.*\.t! (and I think in ext/
> DynaLoader)
>
> 6: For each file only in the newer MANIFEST
> a: Grab the description line from MANIFEST
> b: Write out an =item section with the filename, and description,
> just
> like http://perl5.git.perl.org/perl.git/blob/maint-5.10:/pod/perl5101delta.pod
Hrm. Why track test changes? Does the end user who's interested in
what's changed since the last version really care?
> Perl is this really powerful language for text manipulation. And fun
> to
> play with. We need to get that message out. :-)
That's what I hear! :-)
Best,
David
Thread Previous
|
Thread Next