develooper Front page | perl.perl5.porters | Postings from June 2009

Re: on the perldelta (was Re: Perl 5.10.1)

Thread Previous | Thread Next
David E. Wheeler
June 30, 2009 12:49
Re: on the perldelta (was Re: Perl 5.10.1)
Message ID:
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.


> 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.


> 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:

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".
> 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

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! :-)



Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About