Further metaconfig updates to Porting/pumpkin.pod

1 files changed, 37 insertions, 27 deletions

diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod
index c385962109..38332c3ba4 100644
--- a/Porting/pumpkin.pod
+++ b/Porting/pumpkin.pod
@@ -292,43 +292,47 @@ F<l1_char_class_tab.h>, and F<perltoc.pod> files
 are all automatically generated by perl scripts.  In general, don't
 patch these directly; patch the data files instead.
 
-F<Configure> and F<config_h.SH> are also automatically generated by
-B<metaconfig>.  In general, you should patch the metaconfig units
-instead of patching these files directly.  However, very minor changes
-to F<Configure> may be made in between major sync-ups with the
-metaconfig units, which tends to be complicated operations.  But be
-careful, this can quickly spiral out of control.  Running metaconfig
-is not really hard.
-
 Also F<Makefile> is automatically produced from F<Makefile.SH>.
 In general, look out for all F<*.SH> files.
 
 Finally, the sample files F<config.sh> and F<config_H> in the
 F<Porting/> subdirectory are generated by the script F<Porting/mksample>.
 
-=head1 How to Make a Distribution
+=head3 Files generated by metaconfig
 
-This section has now been expanded and moved into its own file,
-F<Porting/release_managers_guide.pod>.
+F<Configure>, F<config_h.SH> and F<Porting/Glossary> are generated by
+B<metaconfig> (see below for more information on how to use this system)
+and direct changes to these files should in general not be pushed to blead.
 
-I've kept some of the subsections here for now, as they don't directly
-relate to building a release any more, but still contain what might be
-useful information - DAPM 7/2009.
+The exceptions are:
 
-=head2 run metaconfig
+=over 4
 
-If you need to make changes to Configure or config_h.SH, it may be best to
-change the appropriate metaconfig units instead, and regenerate Configure.
+=item *
+
+security fixes
 
-	mconfig -m -O
+=item *
 
-will regenerate F<Configure> and F<config_h.SH>.  Much more information
-on obtaining and running metaconfig is in the F<U/README> file
-that comes with Perl's metaconfig units. See the head of Configure for the
-recent information on how to obtain the units and the tools. The base boils
-down to
+changes pre-approved by the metaconfig maintainers
 
-`	git clone github.com:perl5-metaconfig/metaconfig metaconfig
+=back
+
+Such changes should also be notified to the metaconfig maintainers.
+
+Alternatively, do consider if the F<*ish.h> files or the hint files might
+be a better place for your changes.
+
+=head1 Working with metaconfig
+
+Information about how to use metaconfig can be found in the F<README>
+and F<README_U> files in the metaconfig repository containing Perl's
+metaconfig units:
+
+	# anonymous clone
+	git clone https://github.com/perl5-metaconfig/metaconfig.git
+	# or using a registered github.com identity with ssh
+	git clone github.com:perl5-metaconfig/metaconfig metaconfig
 
 Since metaconfig is hard to change, running correction scripts after
 this generation is sometimes needed. Configure gained complexity over
@@ -337,8 +341,14 @@ when compiling perl. Therefor, you need to run Porting/config_h.pl
 after that generation. All that and more is described in the README
 files that come with the metaunits.
 
-Alternatively, do consider if the F<*ish.h> files or the hint files might
-be a better place for your changes.
+=head1 How to Make a Distribution
+
+This section has now been expanded and moved into its own file,
+F<Porting/release_managers_guide.pod>.
+
+I've kept some of the subsections here for now, as they don't directly
+relate to building a release any more, but still contain what might be
+useful information - DAPM 7/2009.
 
 =head2 MANIFEST
 
@@ -1386,4 +1396,4 @@ All opinions expressed herein are those of the authorZ<>(s).
 
 =head1 LAST MODIFIED
 
-2017-10-13 H.Merijn Brand
+2017-10-13 Dominic Hargreaves