search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.97k stars 556 forks source link

write a Porting/README explaining Porting contents #12721

Closed p5pRT closed 11 years ago

p5pRT commented 11 years ago

Migrated from rt.perl.org#116477 (status was 'resolved')

Searchable as RT116477$

p5pRT commented 11 years ago

From @rjbs

The ./Porting directory in perl.git contains a bunch of stuff used to build\, test\, or torture perl. There are a lot of files in there.

Add a README (or something) file to ./Porting that lists each file and its purpose. If the program isn't mentioned in Porting/release_managers_guide.pod\, figure out where\, if anywhere\, it is mentioned. If you can't figure it out\, flag it as maybe just being cruft.

For extra credit\, add a test to t/porting that asserts that every file in ./Porting is in the explanatory file\, and that nothing in the README doesn't exist on disk.

p5pRT commented 11 years ago

From @jkeenan

On Mon Jan 21 08​:00​:50 2013\, rjbs wrote​:

The ./Porting directory in perl.git contains a bunch of stuff used to build\, test\, or torture perl. There are a lot of files in there.

Add a README (or something) file to ./Porting that lists each file and its purpose. If the program isn't mentioned in Porting/release_managers_guide.pod\, figure out where\, if anywhere\, it is mentioned. If you can't figure it out\, flag it as maybe just being cruft.

For extra credit\, add a test to t/porting that asserts that every file in ./Porting is in the explanatory file\, and that nothing in the README doesn't exist on disk.

We're starting to plan a New York Perl Hackathon and this looks like a good topic.

However\, since that event may be several weeks off\, if someone else *really\, really* wants to work on this ticket\, feel free to Steal it from me.

Thank you very much. Jim Keenan

p5pRT commented 11 years ago

The RT System itself - Status changed from 'new' to 'open'

p5pRT commented 11 years ago

From @jkeenan

On Wed Jan 23 15​:59​:49 2013\, jkeenan wrote​:

On Mon Jan 21 08​:00​:50 2013\, rjbs wrote​:

The ./Porting directory in perl.git contains a bunch of stuff used to build\, test\, or torture perl. There are a lot of files in there.

Add a README (or something) file to ./Porting that lists each file and its purpose. If the program isn't mentioned in Porting/release_managers_guide.pod\, figure out where\, if anywhere\, it is mentioned. If you can't figure it out\, flag it as maybe just being cruft.

For extra credit\, add a test to t/porting that asserts that every file in ./Porting is in the explanatory file\, and that nothing in the README doesn't exist on disk.

We're starting to plan a New York Perl Hackathon and this looks like a good topic.

However\, since that event may be several weeks off\, if someone else *really\, really* wants to work on this ticket\, feel free to Steal it from me.

Thank you very much. Jim Keenan

The patch is the work of Matthew Ryder\, Arthur Goldstein and myself at New York Perl Hackathon. Our objective was to create a first draft\, not a perfect document. We ask that you review this patch with respect to the following priorities​:

(1) Rule out obvious errors.

(2) Improvements in descriptions of files in Porting/.

(3) Stylistic/grammatical/typographical corrections.

When you read this document\, you will no doubt spot references to Perl core functionality that is long dead. We ask that you not use *this RT ticket* discuss whether or not we should retain certain of these Porting files; open up separate tickets for that.

We'll have to decide whether this README is sufficiently useful to be included (with edits) in Perl 5.18 this spring.

Thank you very much. Jim Keenan

p5pRT commented 11 years ago

From @jkeenan

From dd980c21ed49b0b681d3447104b49bac19d4dbc9 Mon Sep 17 00​:00​:00 2001 From​: James E Keenan \jkeenan@​cpan\.org Date​: Sat\, 2 Mar 2013 13​:02​:29 -0500 Subject​: [PATCH] Add README for Porting directory.

Includes work by Matthew Ryder and Arthur Goldstein at New York Perl Hackathon.

For​: RT #116477

Porting/README.pod | 366 ++++++++++++++++++++++++++++++++++++++++++++++++++++ Porting/pod_lib.pl | 35 +++++- 2 files changed\, 399 insertions(+)\, 2 deletions(-) create mode 100644 Porting/README.pod

Inline Patch ```diff diff --git a/Porting/README.pod b/Porting/README.pod new file mode 100644 index 0000000..fbb01e4 --- /dev/null +++ b/Porting/README.pod @@ -0,0 +1,366 @@ +=head1 NAME + +README.pod - README for the F directory in the Perl 5 core distribution. + +=head1 FILES + +=head2 F + +Generates the text which goes in the Acknowledgements section in +a perldelta. You pass in the previous version and it guesses the next +version, fetches information from the repository and outputs the +text. + +=head2 F + +Program to prepare dual-life distributions for insertion into the Perl 5 +F and F directories. Now thought to be largely superseded. + +=head2 F + +=head2 F and F + +Use C to pinpoint changes. + +=head2 F + +A utility to find, and optionally bump, references to the perl version +number in various files within the perl source. + +=head2 F + +Scans the commit logs for commits that are potentially, illegitimately +touching modules that are primarily maintained outside of the perl core. +Also checks for commits that span multiple distributions in cpan/ or dist/. +Makes sure that updated CPAN distributions also update +F, +but otherwise ignores changes to that file (and F). + +=head2 F + +Performs pathname portability checks, including whether there are naming +conflicts when names are truncated to the DOSish, case-ignoring 8.3 format. + +=head2 F + +Performs quality checks on F including rectifying cases where +contributors have submitted contributions from different email addresses. + +=head2 F + +Checks that all the URLs in the Perl source are valid. + +=head2 F + +Check source code for ANSI-C violations. + +=head2 F + +Check that the various F-clones have (at least) all the same symbols +as the top-level F so that the (potentially) needed symbols are not +lagging after how F thinks the world is laid out. VMS is probably not +handled properly here, due to their own rather elaborate DCL scripting. + +=head2 check-cpan-polution + +Scans the commit logs for commits that are potentially, illegitimately touching modules that are primarily maintained outside of the perl core. +Also checks for commits that span multiple distributions in F or +F. Makes sure that updated CPAN distributions also update +F, +but otherwise ignores changes to that file (and F). + +=head2 F + +Check if POD files contain non-ASCII without specifying +encoding. Run it as: C. + +=head2 F + +Check that all the URLs in the Perl source are valid + +=head2 F + +Check the tree against missing VERSIONs. + +=head2 F + +Command line tool to update cherrymaint; a tool for selecting commits from +blead to cherry-pick into stable perl versions. + +=head2 F + +Compare the current Perl source tree and a given tag for modules that have +identical version numbers but different contents. + +=head2 F + +This file is a sample F file. If you are unable +to successfully run F, copy this file to F and +edit it to suit your system. + +=head2 F + +This script reorders F after metaconfig. Changing F +is too complicated This script is run just after F, and it is run +ONLY ONCE. Not to be used afterwards + +=head2 F + +This file was produced by running the F script. It holds all the +definitions figured out by F. Should you modify one of these values, +do not forget to propagate your changes by running C. You may +instead choose to run each of the F<.SH> files by yourself, or C. + +=head2 F + +Compare CPAN modules with their equivalent in core. +Originally based on App::DualLivedDiff by Steffen Mueller. + +=head2 F + +Reports, in a perl source tree, which dual-lived core modules have not the same version than the corresponding module on CPAN. + +=head2 F + +Generates info for Module::CoreList from this perl tree run this from the root +of a perl tree Data is on STDOUT. With an optional arg specifying the root of +a CPAN mirror, outputs the %upstream and %bug_tracker hashes too. + +=head2 F + +Convert certain files in the Perl distribution that need to be in CR-LF format +to CR-LF, or back to LF format (with the -r option). The CR-LF format is NOT +to be used for checking in files to the Perforce repository, but it IS to be +used when making Perl snapshots or releases. + +=head2 F + +List of Perl release epigraphs. + +=head2 F + +This file contains a list of files that F will ensure get an +executable bit. + +=head2 F + +Brute force testing for F. + +Expand C macros using the C preprocessor. + +=head2 F + +This script finds reentrant variants of functions used in an executable and shared objects. + +=head2 F + +This script contains the subroutine to generate a F<.patch file> for a +committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal +digits which acts the internal unique identifier for this commit +(lilypond.org). Related file: F + +=head2 F + +This script, a rough draft, aids in generating a perldelta file +from a series of git commits. + +=head2 F + +This script, given a Perforce change number, outputs the equivalent git commit +id. + +=head2 F + +This script creates a tag for every p4raw-id. + +=head2 F + +This file is built by F. This file contains a description of all +the shell variables whose value is determined by the Configure script. +=head2 F + +This file contains a specification as to how to write a perldelta pod. +Related file: F + +=head2 F + +This script executes every line in every file in the build directy and its +subdirectories to determine if the number of SVs goes up and reports it as a +leak to STDOUT. WARNING! some harm could be done if a line contains something +similar to C<`rm *`>. + +=head2 F + +This script shows information about the maintainers of core files/modules. + +Related files: F, F + +=head2 F + +A package associating core files/modules with maintainers. +Related files: F, F + +=head2 F + +A package to search and show information about which core files/modules are +associated with maintainers. +Related files: F, F + +=head2 F + +This script creates a release checklist as a simple HTML document. + +=head2 F + +This script reads sha1 from C<@ARGV> and then prints GitUtils::gen_dot_patch +to STDOUT to determine which primary branch sha1 can be found on. + +=head2 F + +This script generates the list of registered CPAN sites in F. + +=head2 F + +This script is a quick and dirty snapshot generator for the perl5.git.perl.org +web page to use to generate the snapshot files. + +=head2 F + +This script creates F and F files. + +=head2 F + +This script builds a Perl release tarball. + +=head2 F + +This script outputs a list of files in F which don't exist and a +list of files that exist and aren't in F. + +=head2 F + +This script sorts the files in F. + +=head2 F + +This script automates the process for creating perldelta.pl. + +=head2 F + +This script outputs the added tests between the two versions of Perl. + +=head2 F + +This is a template for a new perldelta file 5.18 description of what the file +does. + +=head2 F + +This seems to be the same file when diffed with the perl5180delta.pod except +that the previous is focused on 5.18.1. + +=head2 F + +Generates info for F from this perl tree. + +=head2 F + +Make it clearer when we haven't run to completion, as we can be quite noisy +when things are working ok write_or_die,pods_to_install does not seem to be +called within in this file. However pods_to_install does call a lot of +libraries inside this file. + +=head2 F + +Generate the sections of files listed in C<%Targets> from F. +Mostly these are rules in Makefiles. + + --verbose gives slightly more output + --build-all tries to build everything + --build-foo updates foo as follows + --showfiles shows the files to be changed + --test exit if perl.pod, MANIFEST are consistent, and regenerated + files are up to date, die otherwise. + +=head2 F + +Applies F to a file. + +=head2 pumpkin.pod + +Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl. + +=head2 F + +The y2038 implementation for perl. This is an implementation of POSIX time.h +which solves the year 2038 bug on systems where time_t is only 32 bits. It is +implemented in bog-standard ANSI C. The latest version can be found at +L. + +=head2 F + +Release announcment for minor releasements of the 5.17 development series. + +=head2 F + +Releasing a new version of perl 5.x. Note that things change at each release, +so there may be new things not covered here, or tools may need updating. + +=head2 F + +This schedule lists the projected or historical development and release +schedules for the next, current and previous stable versions of Perl. Dates +with all question marks will only be releases if deemed necessary by the +Pumpking. + +=head2 F + + List patches in rt. + +=head2 F + +This is a script for sorting the warning and error messages in +F. POD formatting, printf-style escapes, non-letter characters, +and case are ignored, as explained in L. + +=head2 F + +Test suite profiling on Tru 64. + +=head2 F + +Script for cleaning out the "known noise" from Third Degree reports: either +noise caused by F itself, or F leaks. + +=head2 F
p5pRT commented 11 years ago

From @tonycoz

On Sat\, Mar 02\, 2013 at 12​:31​:47PM -0800\, James E Keenan via RT wrote​:

The patch is the work of Matthew Ryder\, Arthur Goldstein and myself at New York Perl Hackathon. Our objective was to create a first draft\, not a perfect document. We ask that you review this patch with respect to the following priorities​:

(1) Rule out obvious errors.

(2) Improvements in descriptions of files in Porting/.

(3) Stylistic/grammatical/typographical corrections.

When you read this document\, you will no doubt spot references to Perl core functionality that is long dead. We ask that you not use *this RT ticket* discuss whether or not we should retain certain of these Porting files; open up separate tickets for that.

We'll have to decide whether this README is sufficiently useful to be included (with edits) in Perl 5.18 this spring.

A few notes​:

Some headings are missing the F\<> markup​:

+ +=head2 check-cpan-polution +

+=head2 pumpkin.pod

There's a missing newline before one heading​:

+This file is built by F\. This file contains a description of all +the shell variables whose value is determined by the Configure script. +=head2 F\<how_to_write_a_perldelta.pod> + +This file contains a specification as to how to write a perldelta pod.

The notes on pod_lib.pl are a little confusing​:

+=head2 F\<pod_lib.pl> + +Make it clearer when we haven't run to completion\, as we can be quite noisy +when things are working ok write_or_die\,pods_to_install does not seem to be +called within in this file. However pods_to_install does call a lot of +libraries inside this file.

The note for config_h.pl is missing a comma or a period (or has some text to be edited out.)

There is no such file as cmpVersion (presumably it should be cmpVERSION.pl)​:

+=head2 F\

Typo​:

+=head2 F\<leakfinder.pl> + +This script executes every line in every file in the build directy and its

The headings are vaguely in alphabetical order\, but there are several exceptions.

corelist-diff\, corelist.pl aren't documented.

There is text describing expand-macro.pl and how_to_write_a_perldelta.pod but no headings.

More generally\, some documentation on when some of the scripts are or should be used would be useful\, eg​:

- config_h.pl - used when importing changes from metaconfig (it's   possible the text is trying to say that\, but an edit seems to have   left behind a text fragment)

- checkAUTHORS.pl - used by porting/authors.t to ensure the authors   list is up to date

- cmpVERSION.pl - used by porting/cmp_version.t to ensure changed   modules have had their versions updated

but it's valuable without this.

Tony

p5pRT commented 11 years ago

From @jkeenan

On Sun Mar 03 15​:04​:48 2013\, tonyc wrote​:

On Sat\, Mar 02\, 2013 at 12​:31​:47PM -0800\, James E Keenan via RT wrote​:

The patch is the work of Matthew Ryder\, Arthur Goldstein and myself at New York Perl Hackathon. Our objective was to create a first draft\, not a perfect document. We ask that you review this patch with respect to the following priorities​:

(1) Rule out obvious errors.

(2) Improvements in descriptions of files in Porting/.

(3) Stylistic/grammatical/typographical corrections.

When you read this document\, you will no doubt spot references to Perl core functionality that is long dead. We ask that you not use *this RT ticket* discuss whether or not we should retain certain of these Porting files; open up separate tickets for that.

We'll have to decide whether this README is sufficiently useful to be included (with edits) in Perl 5.18 this spring.

A few notes​:

Some headings are missing the F\<> markup​:

+ +=head2 check-cpan-polution +

+=head2 pumpkin.pod

[snip]

Thanks for the feedback. Second version attached. Since this is a new file\, I'll just keep posting the latest draft of the entire file until there's one we like enough to commit to blead.

Thank you very much. Jim Keenan

p5pRT commented 11 years ago

From @jkeenan

116477_porting_readme.v2.pod

p5pRT commented 11 years ago

From @tonycoz

On Sun\, Mar 03\, 2013 at 04​:31​:41PM -0800\, James E Keenan via RT wrote​:

Thanks for the feedback. Second version attached. Since this is a new file\, I'll just keep posting the latest draft of the entire file until there's one we like enough to commit to blead.

All the errors I mentioned have been fixed except for​:

- the cmpVersion heading was changed to cmpVersion.pl but it's   actually cmpVERSION.pl

=head2 F\<make_dot_patch.pl>

This script reads sha1 from C\<@​ARGV> and then prints GitUtils​::gen_dot_patch to STDOUT to determine which primary branch sha1 can be found on.

Perhaps​:

  Generate a C\<.patch> file to STDOUT for the specified commit id.

=head2 F\<perl5180delta.pod>

This is a template for a new perldelta file 5.18 description of what the file does.

This isn't a template\, but is a work-in-progress perldelta for 5.18.0. It will probably go away (or be renamed into pod/) once 5.18.0 is released.

=head2 F\<perldelta_template.pod>

This seems to be the same file when diffed with the perl5180delta.pod except that the previous is focused on 5.18.1.

This one is the template. Neither file mentions 5.18.1.

=head2 F\<rt_list_patches>

List patches in rt.

I don't think this should be indented.

Tony

p5pRT commented 11 years ago

From @jkeenan

On Sun Mar 03 17​:18​:41 2013\, tonyc wrote​:

On Sun\, Mar 03\, 2013 at 04​:31​:41PM -0800\, James E Keenan via RT wrote​:

Thanks for the feedback. Second version attached.

version 3 attached.

p5pRT commented 11 years ago

From @jkeenan

116477_porting_readme.v3.pod

p5pRT commented 11 years ago

From @tonycoz

On Sun\, Mar 03\, 2013 at 06​:20​:01PM -0800\, James E Keenan via RT wrote​:

On Sun Mar 03 17​:18​:41 2013\, tonyc wrote​:

On Sun\, Mar 03\, 2013 at 04​:31​:41PM -0800\, James E Keenan via RT wrote​:

Thanks for the feedback. Second version attached.

version 3 attached.

I'm happy.

Tony

p5pRT commented 11 years ago

From @jkeenan

On Mon Mar 04 14​:14​:24 2013\, tonyc wrote​:

On Sun\, Mar 03\, 2013 at 06​:20​:01PM -0800\, James E Keenan via RT wrote​:

On Sun Mar 03 17​:18​:41 2013\, tonyc wrote​:

On Sun\, Mar 03\, 2013 at 04​:31​:41PM -0800\, James E Keenan via RT wrote​:

Thanks for the feedback. Second version attached.

version 3 attached.

I'm happy.

Tony

Anyone else want to chime in? Otherwise\, I'll commit this to blead in about three days.

Thank you very much. Jim Keenan

p5pRT commented 11 years ago

From @b2gills

On Mon\, Mar 4\, 2013 at 6​:25 PM\, James E Keenan via RT \perlbug\-followup@&#8203;perl\.org wrote​:

On Mon Mar 04 14​:14​:24 2013\, tonyc wrote​:

On Sun\, Mar 03\, 2013 at 06​:20​:01PM -0800\, James E Keenan via RT wrote​:

On Sun Mar 03 17​:18​:41 2013\, tonyc wrote​:

On Sun\, Mar 03\, 2013 at 04​:31​:41PM -0800\, James E Keenan via RT wrote​:

Thanks for the feedback. Second version attached.

version 3 attached.

I'm happy.

Tony

Anyone else want to chime in? Otherwise\, I'll commit this to blead in about three days.

Thank you very much. Jim Keenan

=head2 F\<curliff.pl>

Convert certain files in the Perl distribution that need to be in CR-LF format to CR-LF\, or back to LF format (with the -r option). The CR-LF format is NOT to be used for checking in files to the Perforce repository\, but it IS to be used when making Perl snapshots or releases.

Perl is now maintained using git not Perforce.

Slightly unrelated​: That file can probably go ( git handles this )

I don't think this should be in there​:

=head2 F\<perl5180delta.pod>

F\ for Perl 5.18.0​: a work-in-progress file.

p5pRT commented 11 years ago

From @rjbs

* James E Keenan via RT \perlbug\-followup@&#8203;perl\.org [2013-03-04T19​:25​:55]

Anyone else want to chime in? Otherwise\, I'll commit this to blead in about three days.

I do want to give it a look-over and maybe futz with it\, but I don't see any reason that this has to happen before its current form is committed. I'd hate to hold things up.

Do we have a test (for t/Porting) that all files in ./Porting are in the index?

-- rjbs

p5pRT commented 11 years ago

From @jkeenan

On 3/4/13 9​:07 PM\, Brad Gilbert wrote​:

On Mon\, Mar 4\, 2013 at 6​:25 PM\, James E Keenan via RT

=head2 F\<curliff.pl>

Convert certain files in the Perl distribution that need to be in CR-LF format to CR-LF\, or back to LF format (with the -r option). The CR-LF format is NOT to be used for checking in files to the Perforce repository\, but it IS to be used when making Perl snapshots or releases.

Perl is now maintained using git not Perforce.

Slightly unrelated​: That file can probably go ( git handles this )

Please open an RT for the removal of that file.

I don't think this should be in there​:

=head2 F\<perl5180delta.pod>

F\ for Perl 5.18.0​: a work-in-progress file.

Do you mean​: It should not be in Porting/README.pod ... or it shouldn't be in the directory at all?

Thank you very much. jimk

p5pRT commented 11 years ago

From @tonycoz

On Mon\, Mar 04\, 2013 at 10​:46​:06PM -0500\, James E Keenan wrote​:

On 3/4/13 9​:07 PM\, Brad Gilbert wrote​:

I don't think this should be in there​:

=head2 F\<perl5180delta.pod>

F\ for Perl 5.18.0​: a work-in-progress file.

Do you mean​: It should not be in Porting/README.pod ... or it shouldn't be in the directory at all?

I don't think it belongs in the README.pod.

Tony

p5pRT commented 11 years ago

From @jkeenan

On Mon Mar 04 19​:30​:27 2013\, rjbs wrote​:

* James E Keenan via RT \perlbug\-followup@&#8203;perl\.org [2013-03- 04T19​:25​:55]

Anyone else want to chime in? Otherwise\, I'll commit this to blead in about three days.

I do want to give it a look-over and maybe futz with it\, but I don't see any reason that this has to happen before its current form is committed. I'd hate to hold things up.

In 7ad311ab4c1db82cc8475436be976d6d564cb024\, I committed something which was equivalent to my 'v3' attachment\, except that I deleted the paragraph about the perl 5.18.0 perldelta.

Are there still inaccuracies in this README? Undoubtedly. For example\, I did not correct two references to the Perforce repository. But now the document is available for all to see. Feel free to open RTs for corrections or -- better still -- for removal from the Porting directory of files which are outmoded.

Do we have a test (for t/Porting) that all files in ./Porting are in the index?

No\, I didn't want to hold up submission of this patch for that purpose. Any test would have to take into account items like the perl 5.18 delta mentioned above\, which are found in the directory but not in the README. That's a task for someone else\, in a new RT.

Thanks again to Matt and Arthur for their work on this at the NY Perl Hackathon.

Closing ticket.

Thank you very much. Jim Keenan

p5pRT commented 11 years ago

@jkeenan - Status changed from 'open' to 'resolved'