VERSIONS: list all past releases

This document now lists all previous releases.

This allows us to verify that documentation refers to actual release
versions.

Test 971 now verifies options-in-versions and all command line options
documentation individually. Fixed a few discrepancies.

Test 1488 verifies libcurl options "Added-in" to exist. Fixed a few
discrepancies there as well.

Closes #16907

tests/Makefile.am

@@ -57,6 +57,7 @@ EXTRA_DIST =        \
  CMakeLists.txt     \
  FILEFORMAT.md      \
  README.md          \
+ allversions.pm     \
  appveyor.pm        \
  azure.pm           \
  devtest.pl         \

tests/allversions.pm

@@ -0,0 +1,48 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+#
+# This software is licensed as described in the file COPYING, which
+# you should have received as part of this distribution. The terms
+# are also available at https://curl.se/docs/copyright.html.
+#
+# You may opt to use, copy, modify, merge, publish, distribute and/or sell
+# copies of the Software, and permit persons to whom the Software is
+# furnished to do so, under the terms of the COPYING file.
+#
+# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+# KIND, either express or implied.
+#
+# SPDX-License-Identifier: curl
+#
+###########################################################################
+
+# populate the has %pastversion hash table with the version number as key and
+# release date as value
+
+sub allversions {
+    my ($file) = @_;
+    open(A, "<$file") ||
+        die "can't open the versions file $file\n";
+    my $before = 1;
+    my $relcount;
+    while(<A>) {
+        if(/^## Past releases/) {
+            $before = 0;
+        }
+        elsif(!$before &&
+              /^- ([0-9.]+): (.*)/) {
+            $pastversion{$1}=$2;
+            $relcount++;
+        }
+    }
+    close(A);
+    die "too few releases ($relcount) found in $file" if($relcount < 100);
+}
+
+1;

tests/data/test1488

@@ -19,7 +19,7 @@ symbols-in-versions and manpages agree on added-in versions
 </name>
 
 <command type="perl">
-%SRCDIR/test1488.pl %SRCDIR/.. ../include/curl
+%SRCDIR/test1488.pl %SRCDIR/.. ../include/curl %SRCDIR/../docs/VERSIONS.md
 </command>
 </client>
 

tests/data/test971

@@ -18,7 +18,7 @@ Verify that options-in-versions and docs/cmdline-opts are in sync
 </name>
 
 <command type="perl">
-%SRCDIR/test971.pl %SRCDIR/../docs/options-in-versions %SRCDIR/../docs/cmdline-opts
+%SRCDIR/test971.pl %SRCDIR/../docs/options-in-versions %SRCDIR/../docs/cmdline-opts %SRCDIR/../docs/VERSIONS.md
 </command>
 </client>
 

tests/test1488.pl

@@ -27,9 +27,9 @@
 # a late evening in the #curl IRC channel.
 #
 
-use strict;
 use warnings;
 use vars qw($Cpreprocessor);
+use allversions;
 
 #
 # configurehelp perl module is generated by configure script
@@ -54,6 +54,7 @@ my $root=$ARGV[0] || ".";
 my $i = ($ARGV[1]) ? "-I$ARGV[1] " : '';
 my $error;
 
+my $versions = $ARGV[2];
 
 my @syms;
 my %manpage;
@@ -70,8 +71,13 @@ sub checkmanpage {
         if(/^Title: (.*)/i) {
             $title = $1;
         }
-        elsif(/^Added-in: (.*)/i) {
+        elsif(/^Added-in: ([an0-9.\/]*)/i) {
             $addedin = $1;
+
+            if(($addedin ne "n/a") && !$pastversion{$addedin}) {
+                print "$m: was added in a never released version: $addedin\n";
+                $error++;
+            }
         }
         if($addedin && $title) {
             if($manpage{$title}) {
@@ -97,17 +103,24 @@ sub scanman_md_dir {
     }
 }
 
+# get all the past versions
+allversions($versions);
+
 scanman_md_dir("$root/docs/libcurl");
 scanman_md_dir("$root/docs/libcurl/opts");
 
 open my $s, "<", "$root/docs/libcurl/symbols-in-versions";
 while(<$s>) {
-    if(/(^[^ \n]+) +(.*)/) {
-        my ($sym, $rest)=($1, $2);
-        my @a=split(/ +/, $rest);
+    chomp;
+    if(/^(\S+) +([0-9.]*)/) {
+        my ($sym, $ver)=($1, $2);
         push @syms, $sym;
 
-        $symadded{$sym}=$a[0];
+        $symadded{$sym}=$ver;
+        if(!$pastversion{$ver}) {
+            printf "SIV: says $sym was added in non-existing %s\n", $ver;
+            $error++;
+        }
     }
 }
 close $s;

tests/test971.pl

@@ -30,8 +30,11 @@
 #   $cmddir
 #
 
+use allversions;
+
 my $opts = $ARGV[0];
 my $cmddir = $ARGV[1];
+my $versions = $ARGV[2];
 
 sub cmdfiles {
     my ($dir)=@_;
@@ -91,6 +94,9 @@ sub versioncheck {
     close($fh);
 }
 
+# get all the past versions
+allversions($versions);
+
 # get all the files
 my @cmdopts = cmdfiles($cmddir);
 
@@ -100,6 +106,12 @@ my @veropts = mentions($opts);
 # check if all files are in the doc
 for my $c (sort @cmdopts) {
     if($oiv{$c}) {
+        if(!$pastversion{$oiv{$c}}) {
+            printf STDERR "$c: %s is not a proper release\n",
+                $oiv{$c};
+            $error++;
+        }
+
         # present, but at same version?
         versioncheck($c, $oiv{$c});
     }