Branch: refs/heads/yves/manifest_dev
Home: https://github.com/Perl/perl5
Commit: a8eaf215b956dfaf97fed974ef1dee201a2d7762
https://github.com/Perl/perl5/commit/a8eaf215b956dfaf97fed974ef1dee201a2d7762
Author: Yves Orton <[email protected]>
Date: 2022-03-11 (Fri, 11 Mar 2022)
Changed paths:
M Porting/README.pod
M Porting/manisort
Log Message:
-----------
manisort: rework, add new convenience option "fix" and add pod, etc
Add a new convenience option to manisort for a common case
manisort --fix=MANIFEST_FILE
is the same as
manisort --nocheck --output=MANIFEST_FILE MANIFEST_FILE
Eg, it runs quietly, returns an exit code of 0 on success and
rewrites the file in correctly sorted order while removing
true dupes.
Commit: e00398bb5491ed0b5aa35d17e683c73fee06158e
https://github.com/Perl/perl5/commit/e00398bb5491ed0b5aa35d17e683c73fee06158e
Author: Yves Orton <[email protected]>
Date: 2022-03-11 (Fri, 11 Mar 2022)
Changed paths:
M Makefile.SH
Log Message:
-----------
Makefile.SH - use new --fix option to manisort and simplify
The --fix option returns true if it worked, and so the use of
the true command is not required.
Commit: 233f92ce8af7fa823c4c510ddbf625c71e95e62a
https://github.com/Perl/perl5/commit/233f92ce8af7fa823c4c510ddbf625c71e95e62a
Author: Yves Orton <[email protected]>
Date: 2022-03-11 (Fri, 11 Mar 2022)
Changed paths:
M Porting/release_managers_guide.pod
Log Message:
-----------
release_managers_guide.pod: point out the --fix option to manisort
Commit: 605f007a22f5bd471878fbc7de3d7569857a1b0f
https://github.com/Perl/perl5/commit/605f007a22f5bd471878fbc7de3d7569857a1b0f
Author: Yves Orton <[email protected]>
Date: 2022-03-11 (Fri, 11 Mar 2022)
Changed paths:
M MANIFEST
M pod/perl.pod
Log Message:
-----------
Add descriptions to dead pods in pod/perl.pod
Even though these pods are dead we should keep their descriptions
for the manifest.
Commit: 21a660d60415c5fba54f60fa7bd58e24c710b117
https://github.com/Perl/perl5/commit/21a660d60415c5fba54f60fa7bd58e24c710b117
Author: Yves Orton <[email protected]>
Date: 2022-03-11 (Fri, 11 Mar 2022)
Changed paths:
M MANIFEST
M Makefile.SH
A Porting/MANIFEST.dev
M Porting/README.pod
M Porting/manicheck
M Porting/manifest_lib.pl
M Porting/release_managers_guide.pod
M t/porting/exec-bit.t
M t/porting/known_pod_issues.dat
M t/porting/manifest.t
M t/porting/readme.t
Log Message:
-----------
Create Porting/MANIFEST.dev as a complement to MANIFEST and related infra
This file is intended to list all the files in the repo which are not
listed in the main MANIFEST file, and which are used only for
development purposes, especially those files which are only useful when
working in a git checkout of the main perl git repository.
The files it contains will NOT be added to the production tarball
release. The file has the exact same format as the main MANIFEST:
"file\t+description" or "file".
Q. Why didn't I call this Porting/MANIFEST as mentioned in the
discussion thread that lead to this patch?
A. The main reason was that Porting/README.pod includes a list of files
in Porting with descriptions and explanations for what the files do
or how they are used. In several places the file refers to
"MANIFEST", which lead to ambiguity that would have had to be
resolved by changing all the entries to refer to "Porting/whatever"
instead. It was much simpler to give the new file an extension, and I
thought that '.dev' suggests it is for "development" purposes.
Q. Why isn't this using MANIFEST.skip style functionality?
A1. Various parts of our build and test process expect to read the
MANIFEST file and then do things based on the entries contained
within. Eg, run tests, or extract data, or compare the file list to
content in another file. Those parts of our build process would
break if we used a skip style list of regexen. So it would be more
work to teach them to deal with such a file, assuming it was
actually doable - given the additional work I have not considered it
deeply. On the other hand teaching that logic to simply read two
files was and is easy.
A2. I think each file we have in the repo should have a description.
This patch currently doesn't provide a description for each, but it
does for many, especially those migrated from MANIFEST.
A3. I think that MANIFEST.skip style files of exclusion regexens and
globs are error prone and easy to mess up, for instance by excluding
far more than you had intended to. They can also be annoying to get
right, obviously not impossible, but sometimes annoying. Explicitly
listing everything is easy in every way, especially to mechanize.
A4. I would like to be able to move verbatim entries from our existing
MANIFEST into the new Porting/MANIFEST.dev, description and all.
MANIFEST.skip style files do not support descriptions except as
comments as far as I recall. That would have meant munging the data
from MANIFEST during the move process which would be annoying.
A5. I would like to be able to reuse our sorting logic to keep the files
nicely sorted in a way where the file is somewhat readable. A list
of skip files would be less amenable to doing so.
Q. There is a lot of duplicated logic related to testing manifests,
should we refactor it out into a module or some resuable tool set?
A. YES! We already have Porting/manifest_lib.pm, but it currently does
not declare a package, and it only contains one function. Instead of
adding yet more code that depends on requiring a file and having it
inject subs into package main I decided that doing the refactoring
could wait for a separate commit or PR. But I definitely think we
should refactor as much of this logic as possible.
Q. Some of the test files were fairly significantly changed, are you
sure you didn't break or drop any of the tests?
A. I am reasonably confident I did not. Secondary review appreciated.
Some of the touched files are quite old and obviously "quick hack"
scripts. By rewriting them quite a bit I was able to simplify and
perform some of the tests in different ways or parts of the script.
As far as I know I didn't drop any.
Q. Why didn't you use newer features in the rewrite?
A. I am a bit conservative in my taste, and I like build tools to be
able to run on older perls, and for things like this I prefer to
stick with what I know well. Patches welcome.
Q. Why didn't you move more of the stuff we shouldn't bundle with
our releases?
A. I figured someone like Nicolas R. (who helped motivate this patch)
would feel left out if I didn't leave him anything to do. :-)
Compare: https://github.com/Perl/perl5/compare/c155bccb38ea...21a660d60415
