Resurrect the Changes file as a simple guide to finding changes

5 files changed, 79 insertions, 9 deletions

diff --git a/AUTHORS b/AUTHORS
index 36edd45e0f..d25c432c7a 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,11 +1,11 @@
 # To give due honour to those who have made Perl 5 what it is today,
 # here are easily-from-changelogs-extractable people and their
-# (hopefully) current and preferred email addresses (as of 2002, if known)
-# from the Changes files.  These people have either submitted
-# patches or suggestions, or their bug reports or comments have inspired
-# the appropriate patches.  Corrections, additions, deletions welcome;
-# send them to perl5-porters@perl.org, preferably as the output of diff(1),
-# diff -u or diff -c between the original and a corrected version of this file.
+# (hopefully) current and preferred email addresses from the commits.
+# These people have either submitted patches or suggestions, or their bug
+# reports or comments have inspired the appropriate patches.  Corrections,
+# additions, deletions welcome; send them to perl5-porters@perl.org,
+# preferably as the output of diff(1), diff -u or diff -c between the
+# original and a corrected version of this file.
 #
 # The use of this database for anything else than Perl development
 # is strictly forbidden.  (Passive distribution with the Perl source
diff --git a/Changes b/Changes
new file mode 100644
index 0000000000..0ffddf6996
--- /dev/null
+++ b/Changes
@@ -0,0 +1,70 @@
+For an overview of what's changed in this release, see pod/perldelta.pod.
+
+For the details of changes in previous releases, see the individual
+perlNNNdelta.pod files. For example, pod/perl588delta.pod describes the
+changes between versions 5.8.7 and 5.8.8.
+
+For a list of contributors to perl, see AUTHORS.
+
+If you need a detailed commit history (i.e. descriptions of each
+individual commit),  you can view the git version control history online
+at http://perl5.git.perl.org/perl.git (follow the 'shortlog' link beside
+the relevant tag). Or, you can download a copy of the git repository and
+then run a command like 
+
+    git log --name-status perl-5.10.0..perl-5.11.0
+
+to view all the changes between 5.10.0 and 5.11.0.
+
+See pod/perlrepository.pod for more details on using git and accessing the
+commit history.
+
+In perl releases prior to 2009, the source tarball included a collection
+of Changes files that listed the individual commits that had gone into
+each release. Since these files had become very large, and since the
+same information is now freely available online, it was decided to remove
+them from subsequent releases.
+
+If you need access to these removed files, then they can be be found most
+recently in the 5.8.9 and 5.10.0 tarballs, at
+
+    http://www.cpan.org/src/perl-5.8.9.tar.gz 
+    http://www.cpan.org/src/perl-5.10.0.tar.gz
+
+The contents of the files in question can mostly be regenerated using git
+commands. The following table shows the equivalents. Note that the files
+prior to Changes5.005 were not simple lists of commits, so can't be
+recreated just by running the git command. As it happens, even the latter
+ones are not exact equivalents. This is due to a combination of errors in
+the original Changes files, and "impedance mismatches" when the previous
+version control data was imported into git in December 2008.
+
+For example, the Changes5.005 file includes 206 spurious entries from the
+maint5.004 Perforce branch.
+
+Running the following command with the range argument shown in the table
+will produce *approximately* the same list of changes in the specified
+file shown from the listed tarball.
+
+    git log --name-status <range>
+
+  file           tarball  <range> argument to 'git log'
+  ------------   ------   --------------------------------
+  Changes5.000   Either   N/A
+  Changes5.001   Either   perl-5.000..perl-5.001
+  Changes5.002   Either   perl-5.001..perl-5.002
+  Changes5.003   Either   perl-5.002..perl-5.003
+  Changes5.004   Either   perl-5.003..perl-5.004
+  Changes5.005   Either   perl-5.004..perl-5.005_03
+  Changes5.6     Either   perl-5.005_03..perl-5.6.0
+  Changes5.8     Either   perl-5.6.0..perl-5.8.0
+  Changes5.8.1   5.8.9    perl-5.8.0..perl-5.8.1 ^1ede746b
+  Changes5.8.2   5.8.9    perl-5.8.1..perl-5.8.2
+  Changes5.8.3   5.8.9    perl-5.8.2..perl-5.8.3
+  Changes5.8.4   5.8.9    perl-5.8.3..perl-5.8.4
+  Changes5.8.5   5.8.9    perl-5.8.4..perl-5.8.5 ^3a81978b
+  Changes5.8.6   5.8.9    perl-5.8.5..perl-5.8.6 ^498d59dd
+  Changes5.8.7   5.8.9    perl-5.8.6..perl-5.8.7
+  Changes5.8.8   5.8.9    perl-5.8.7..perl-5.8.8
+  Changes        5.8.9    perl-5.8.8..perl-5.8.9
+  Changes        5.10.0   perl-5.8.0..perl-5.10.0
diff --git a/INSTALL b/INSTALL
index d8485758b4..004dccea6e 100644
--- a/INSTALL
+++ b/INSTALL
@@ -42,8 +42,8 @@ If you have problems, corrections, or questions, please see
 L<"Reporting Problems"> below.
 
 For information on what's new in this release, see the
-pod/perl5110delta.pod file.  For more detailed information about specific
-changes, see the Changes file.
+pod/perl5110delta.pod file.  For more information about how to find more
+specific detail about changes, see the Changes file.
 
 =head1 DESCRIPTION
 
diff --git a/MANIFEST b/MANIFEST
index b7ace8c6e2..e824679ca8 100755
--- a/MANIFEST
+++ b/MANIFEST
@@ -9,6 +9,7 @@ beos/beosish.h		BeOS port
 beos/nm.c		BeOS port
 cc_runtime.h		Macros need by runtime of compiler-generated code
 cflags.SH		A script that emits C compilation flags per file
+Changes			Describe how to peruse changes between releases
 config_h.SH		Produces config.h
 configpm		Produces lib/Config.pm
 Configure		Portability tool
diff --git a/README.cygwin b/README.cygwin
index 14640c6784..1876f99a4a 100644
--- a/README.cygwin
+++ b/README.cygwin
@@ -558,7 +558,6 @@ be kept as clean as possible.
 =item Documentation
 
   INSTALL README.cygwin README.win32 MANIFEST
-  Changes Changes5.004 Changes5.005 Changes5.6 Changes5.8
   pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
   pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
   pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod