Front page | perl.perl5.porters |
Postings from June 2009
on the perldelta (was Re: Perl 5.10.1)
Thread Previous
|
Thread Next
From:
Nicholas Clark
Date:
June 30, 2009 12:12
Subject:
on the perldelta (was Re: Perl 5.10.1)
Message ID:
20090630191228.GL33745@plum.flirble.org
On Wed, Jun 24, 2009 at 12:04:30PM +0200, demerphq wrote:
> 2009/6/24 David Golden <xdaveg@gmail.com>:
> > It's not perldelta, it's the stability standards. We've had that argument.
>
> Regardless as to whether this argument already occured I personally DO
> think it is in a big part the actual writing of the perldelta.
>
> We consider stability standards when we apply patches, so we already
> put more effort into THAT aspect than we do in making sure that
> perldelta is updated with what we have changed. Thus i think the main
> problem is writing the perldelta. Its not easy to reverse engineer the
> perldelta remarks from the commits that have been applied.
True.
> > I might say that the problem is the magnitude of delta-perl, which is
> > one of the things that causes so much concern over stability. Shorter
> > release cycles means smaller scope of changes, which means lower risk
> > and more confidence.
>
> Yes, it does make writing the perldelta psychologicially easier, as
> one has less haystacks to search. I dont know if actually changes much
> overall for reasons i stated above.
Yes.
I've managed to mislay the messages that discuss things in more detail.
But from memory, and based partly on the recent experience of grinding
through just over 50% of maint-5.10's commits:
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.
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:
http://perl5.git.perl.org/perl.git/commit/f6722d80bdc33aac8a78ab0f35acbb2f94ce990c
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.
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]
=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
=item Modules and Pragmata
All changes to installed files in F<ext/> and F<lib/> go here, in a list
ordered by distribution name. Minimally it should be the module version,
but it's more useful to the end user to give a paragraph's summary of the
module's changes. In an ideal world, dual-life modules would have a
F<Changes> file that could be cribbed.
Start with Porting/cmpVERSION.pl
Augment it with a flag, so that instead of reporting which modules are
different but have the same version, report on modules which *are* different.
Grab the old version from the exploded tarball, and the new version from
the git checkout, and output the line
=item *
C<less> upgraded from version 0.01 to 0.02
That's a start.
Once that's done, a more adventurous enhancement is to use the API in
Porting/Maintainers.pm to work out if a module is dual lived. If it is,
grab the relevant changes files from CPAN for the old and new versions,
and if the old one is a strict subset of the new one, splice the extra
lines right into the output, as a basis for summarising.
(And if not, experiment with using git to get the relevant part of changelog
for the particular file in core)
These could also be enhanced further by using a Pod parser module to produce
a parse tree of perl${whatever}delta.pod, and splicing in the updates
correctly without throwing existing entries away.
If you think that's nuts, take a look at what pod/buildtoc already does to
splice into existing Makefiles on various platforms:
http://perl5.git.perl.org/perl.git/blob/blead:/pod/buildtoc#l498
Perl is this really powerful language for text manipulation. And fun to
play with. We need to get that message out. :-)
Nicholas Clark
Thread Previous
|
Thread Next