release-tools/release-aux/ documentation updates and small fixes

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/tools/pull/140)

diff --git a/release-tools/release-aux/README.md b/release-tools/release-aux/README.md
index a0438f06b23baf625054d6ed3e1cdc0a8ba4918b..a9db386bbd6a4f1736aff2bfdc25da7c1a29d68d 100644 (file)
--- a/release-tools/release-aux/README.md
+++ b/release-tools/release-aux/README.md
@@ -1,7 +1,7 @@
 Auxillary files for dev/release.sh
 ===================================
 
-- release-state-fn.sh
+- `release-state-fn.sh`
 
   This is the main version and state update logic...  you could say
   that it's the innermost engine for the release mechanism.  It
@@ -9,22 +9,29 @@ Auxillary files for dev/release.sh
   release-version-fn.sh to supply necessary functions that are
   specific for versioning schemes.
 
-- release-version-fn.sh
+- `release-version-fn.sh`
 
-  Supplies functions that are specific to versioning schemes:
+  Supplies functions to manipulate version data appropriately for the
+  detected version scheme:
 
-  get_version() gets the version data from appropriate files.
+  `get_version()` gets the version data from appropriate files.
 
-  set_version() writes the version data to appropriate files.
+  `set_version()` writes the version data to appropriate files.
 
-  fixup_version() updates the version data, given a first argument
+  `fixup_version()` updates the version data, given a first argument
   that instructs it what update to do.
 
-- openssl-announce-pre-release.tmpl and openssl-announce-release.tmpl
+- `openssl-announce-pre-release.tmpl` and `openssl-announce-release.tmpl`
 
   Templates for announcements
 
-- fixup-*-release.pl and fixup-*-postrelease.pl
+- `fixup-*-release.pl` and `fixup-*-postrelease.pl`
 
   Fixup scripts for specific files, to be done for the release
   commit and for the post-release commit.
+
+  Some of the scripts have very similar names, to handle different file layouts.
+  For example, `fixup-CHANGES.md-postrelease.pl` handles the file `CHANGES.md`
+  that is used in OpenSSL 3.0 and on, while `fixup-CHANGES-postrelease.pl`
+  handles the file `CHANGES` that is used in pre-3.0 OpenSSL versions.
+  Do not confuse these or other similarly named scripts.

diff --git a/release-tools/release-aux/release-state-fn.sh b/release-tools/release-aux/release-state-fn.sh
index 267d8753d5c89a8b7cbd92db70af0d9fe0a46b58..83e71cc50425e8b7263c4fd42fd12af2827a25d2 100644 (file)
--- a/release-tools/release-aux/release-state-fn.sh
+++ b/release-tools/release-aux/release-state-fn.sh
@@ -1,5 +1,5 @@
 #! /bin/sh
-# Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
 #
 # Licensed under the Apache License 2.0 (the "License").  You may not use
 # this file except in compliance with the License.  You can obtain a copy
@@ -37,10 +37,20 @@
 #               should only be used in the master branch when a release branch
 #               has been created.
 #
-# This function expects there to be a function called fixup_version(), which
-# SHOULD take the |next| as first argument, and SHOULD increase the label
-# counter or the PATCH number accordingly, but only when the current
-# state is "in development".
+# This function uses a private function _fixup_version(), which takes |next|
+# value as first argument, and SHOULD increase the label counter or the PATCH
+# number accordingly, but only when the current state is "in development".
+
+# The following global variables are manipulated, either directly here or
+# by the fixup_version function:
+#
+# PRE_LABEL
+# PRE_NUM
+# PATCH
+# VERSION
+# SERIES
+# TYPE
+# RELEASE_DATE
 
 next_release_state () {
     local next="$1"
@@ -151,6 +161,7 @@ next_release_state () {
             # fixup_version() should trip up the PATCH number.
             + )
                 TYPE=dev
+                RELEASE_DATE=
                 fixup_version ""
                 ;;