release-tools/release.sh

   1 #! /bin/bash -e
   2 # Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
   3 #
   4 # Licensed under the Apache License 2.0 (the "License").  You may not use
   5 # this file except in compliance with the License.  You can obtain a copy
   6 # in the file LICENSE in the source distribution or at
   7 # https://www.openssl.org/source/license.html
   8
   9 # This is the most shell agnostic way to specify that POSIX rules.
  10 POSIXLY_CORRECT=1
  11
  12 # Force C locale because some commands (like date +%b) relies
  13 # on the current locale.
  14 export LC_ALL=C
  15
  16 usage () {
  17     cat <<EOF
  18 Usage: release.sh [ options ... ]
  19
  20 --alpha         Start or increase the "alpha" pre-release tag.
  21 --next-beta     Switch to the "beta" pre-release tag after alpha release.
  22                 It can only be given with --alpha.
  23 --beta          Start or increase the "beta" pre-release tag.
  24 --final         Get out of "alpha" or "beta" and make a final release.
  25                 Implies --branch.
  26
  27 --branch        Create a release branch 'openssl-{major}.{minor}',
  28                 where '{major}' and '{minor}' are the major and minor
  29                 version numbers.
  30
  31 --reviewer=<id> The reviewer of the commits.
  32 --local-user=<keyid>
  33                 For the purpose of signing tags and tar files, use this
  34                 key (default: use the default e-mail address’ key).
  35
  36 --no-upload     Don't upload to upload@dev.openssl.org.
  37 --no-update     Don't perform 'make update' and 'make update-fips-checksums'.
  38 --verbose       Verbose output.
  39 --debug         Include debug output.  Implies --no-upload.
  40
  41 --force         Force execution
  42
  43 --help          This text
  44 --manual        The manual
  45
  46 If none of --alpha, --beta, or --final are given, this script tries to
  47 figure out the next step.
  48 EOF
  49     exit 0
  50 }
  51
  52 # Set to one of 'major', 'minor', 'alpha', 'beta' or 'final'
  53 next_method=
  54 next_method2=
  55
  56 do_branch=false
  57 warn_branch=false
  58
  59 do_clean=true
  60 do_upload=true
  61 do_update=true
  62 DEBUG=:
  63 VERBOSE=:
  64 git_quiet=-q
  65
  66 force=false
  67
  68 do_help=false
  69 do_manual=false
  70
  71 tagkey=' -s'
  72 gpgkey=
  73 reviewers=
  74
  75 upload_address=upload@dev.openssl.org
  76
  77 TEMP=$(getopt -l 'alpha,next-beta,beta,final' \
  78               -l 'branch' \
  79               -l 'no-upload,no-update' \
  80               -l 'verbose,debug' \
  81               -l 'local-user:' \
  82               -l 'reviewer:' \
  83               -l 'force' \
  84               -l 'help,manual' \
  85               -n release.sh -- - "$@")
  86 eval set -- "$TEMP"
  87 while true; do
  88     case $1 in
  89     --alpha | --beta | --final )
  90         next_method=$(echo "x$1" | sed -e 's|^x--||')
  91         if [ -z "$next_method2" ]; then
  92             next_method2=$next_method
  93         fi
  94         shift
  95         if [ "$next_method" = 'final' ]; then
  96             do_branch=true
  97         fi
  98         ;;
  99     --next-beta )
 100         next_method2=$(echo "x$1" | sed -e 's|^x--next-||')
 101         shift
 102         ;;
 103     --branch )
 104         do_branch=true
 105         warn_branch=true
 106         shift
 107         ;;
 108     --no-upload )
 109         do_upload=false
 110         shift
 111         ;;
 112     --no-update )
 113         do_update=false
 114         shift
 115         ;;
 116     --verbose )
 117         VERBOSE=echo
 118         git_quiet=
 119         shift
 120         ;;
 121     --debug )
 122         DEBUG=echo
 123         do_upload=false
 124         shift
 125         ;;
 126     --local-user )
 127         shift
 128         tagkey=" -u $1"
 129         gpgkey=" -u $1"
 130         shift
 131         ;;
 132     --reviewer )
 133         reviewers="$reviewers $1=$2"
 134         shift
 135         shift
 136         ;;
 137     --force )
 138         force=true
 139         shift
 140         ;;
 141     --help )
 142         usage
 143         exit 0
 144         ;;
 145     --manual )
 146         sed -e '1,/^### BEGIN MANUAL/d' \
 147             -e '/^### END MANUAL/,$d' \
 148             < "$0" \
 149             | pod2man \
 150             | man -l -
 151         exit 0
 152         ;;
 153     -- )
 154         shift
 155         break
 156         ;;
 157     * )
 158         echo >&2 "Unknown option $1"
 159         shift
 160         exit 1
 161         ;;
 162     esac
 163 done
 164
 165 $DEBUG >&2 "DEBUG: \$next_method=$next_method"
 166 $DEBUG >&2 "DEBUG: \$next_method2=$next_method2"
 167
 168 $DEBUG >&2 "DEBUG: \$do_branch=$do_branch"
 169
 170 $DEBUG >&2 "DEBUG: \$do_upload=$do_upload"
 171 $DEBUG >&2 "DEBUG: \$do_update=$do_update"
 172 $DEBUG >&2 "DEBUG: \$DEBUG=$DEBUG"
 173 $DEBUG >&2 "DEBUG: \$VERBOSE=$VERBOSE"
 174 $DEBUG >&2 "DEBUG: \$git_quiet=$git_quiet"
 175
 176 case "$next_method+$next_method2" in
 177     major+major | minor+minor )
 178         # These are expected
 179         ;;
 180     alpha+alpha | alpha+beta | beta+beta | final+final | + | +beta )
 181         # These are expected
 182         ;;
 183     * )
 184         echo >&2 "Internal option error ($next_method, $next_method2)"
 185         exit 1
 186         ;;
 187 esac
 188
 189 # Verbosity feed for certain commands
 190 VERBOSITY_FIFO=/tmp/openssl-$$.fifo
 191 mkfifo -m 600 $VERBOSITY_FIFO
 192 ( cat $VERBOSITY_FIFO | while read L; do $VERBOSE "> $L"; done ) &
 193 exec 42>$VERBOSITY_FIFO
 194 trap "exec 42>&-; rm $VERBOSITY_FIFO" 0 2
 195
 196 # Setup ##############################################################
 197
 198 # Check that we have the scripts that define functions we use
 199 RELEASE_AUX=$(cd $(dirname $0)/release-aux; pwd)
 200 found=true
 201 for fn in "$RELEASE_AUX/release-version-fn.sh" \
 202           "$RELEASE_AUX/release-state-fn.sh"; do
 203     if ! [ -f "$fn" ]; then
 204         echo >&2 "'$fn' is missing"
 205         found=false
 206     fi
 207 done
 208 if ! $found; then
 209     exit 1
 210 fi
 211
 212 # Load version functions
 213 . $RELEASE_AUX/release-version-fn.sh
 214 . $RELEASE_AUX/release-state-fn.sh
 215
 216 # Make sure we're in the work directory, and remember it
 217 if HERE=$(git rev-parse --show-toplevel); then
 218     :
 219 else
 220     echo >&2 "Not in a git worktree"
 221     exit 1
 222 fi
 223
 224 # Make sure that it's a plausible OpenSSL work tree, by checking
 225 # that a version file is found
 226 get_version
 227
 228 if [ -z "$VERSION_FILE" ]; then
 229     echo >&2 "Couldn't find OpenSSL version data"
 230     exit 1
 231 fi
 232
 233 # Make sure it's a branch we recognise
 234 orig_branch=$(git rev-parse --abbrev-ref HEAD)
 235 if (echo "$orig_branch" \
 236         | grep -E -q \
 237                -e '^master$' \
 238                -e '^OpenSSL_[0-9]+_[0-9]+_[0-9]+[a-z]*-stable$' \
 239                -e '^openssl-[0-9]+\.[0-9]+$'); then
 240     :
 241 elif $force; then
 242     :
 243 else
 244     echo >&2 "Not in master or any recognised release branch"
 245     echo >&2 "Please 'git checkout' an appropriate branch"
 246     exit 1
 247 fi
 248 orig_HEAD=$(git rev-parse HEAD)
 249
 250 # Initialize #########################################################
 251
 252 echo "== Initializing work tree"
 253
 254 # Generate a cloned directory name
 255 release_clone="$orig_branch-release-tmp"
 256
 257 echo "== Work tree will be in $release_clone"
 258
 259 # Make a clone in a subdirectory and move there
 260 if ! [ -d "$release_clone" ]; then
 261     $VERBOSE "== Cloning to $release_clone"
 262     git clone $git_quiet -b "$orig_branch" -o parent . "$release_clone"
 263 fi
 264 cd "$release_clone"
 265
 266 get_version
 267
 268 # Branches we will work with.  The release branch is where we make the
 269 # changes for the release, the update branch is where we make the post-
 270 # release changes
 271 update_branch="$orig_branch"
 272 release_branch="$(std_branch_name)"
 273
 274 # among others, we only create a release branch if the patch number is zero
 275 if [ "$update_branch" = "$release_branch" ] || [ $PATCH -ne 0 ]; then
 276     if $do_branch && $warn_branch; then
 277         echo >&2 "Warning! We're already in a release branch; --branch ignored"
 278     fi
 279     do_branch=false
 280 fi
 281
 282 if ! $do_branch; then
 283     release_branch="$update_branch"
 284 fi
 285
 286 # Branches we create for PRs
 287 branch_version="$VERSION${PRE_LABEL:+-$PRE_LABEL$PRE_NUM}"
 288 tmp_update_branch="OSSL--$update_branch--$branch_version"
 289 tmp_release_branch="OSSL--$release_branch--$branch_version"
 290
 291 # Check that we're still on the same branch as our parent repo, or on a
 292 # release branch
 293 current_branch=$(git rev-parse --abbrev-ref HEAD)
 294 if [ "$current_branch" = "$update_branch" ]; then
 295     :
 296 elif [ "$current_branch" = "$release_branch" ]; then
 297     :
 298 else
 299     echo >&2 "The cloned sub-directory '$release_clone' is on a branch"
 300     if [ "$update_branch" = "$release_branch" ]; then
 301         echo >&2 "other than '$update_branch'."
 302     else
 303         echo >&2 "other than '$update_branch' or '$release_branch'."
 304     fi
 305     echo >&2 "Please 'cd \"$(pwd)\"; git checkout $update_branch'"
 306     exit 1
 307 fi
 308
 309 SOURCEDIR=$(pwd)
 310 $DEBUG >&2 "DEBUG: Source directory is $SOURCEDIR"
 311
 312 # Release ############################################################
 313
 314 # We always expect to start from a state of development
 315 if [ "$TYPE" != 'dev' ]; then
 316     echo >&2 "Not in a development branch"
 317     echo >&2 "Have a look at the git log in $release_clone, it may be that"
 318     echo >&2 "a previous crash left it in an intermediate state and that"
 319     echo >&2 "need to drop the top commit:"
 320     echo >&2 ""
 321     echo >&2 "(cd $release_clone; git reset --hard HEAD^)"
 322     echo >&2 "# WARNING! LOOK BEFORE YOU ACT"
 323     exit 1
 324 fi
 325
 326 # Update the version information.  This won't save anything anywhere, yet,
 327 # but does check for possible next_method errors before we do bigger work.
 328 next_release_state "$next_method"
 329
 330 # Create our temporary release branch
 331 $VERBOSE "== Creating a local release branch: $tmp_release_branch"
 332 git checkout $git_quiet -b "$tmp_release_branch"
 333
 334 echo "== Configuring OpenSSL for update and release.  This may take a bit of time"
 335
 336 ./Configure cc >&42
 337
 338 $VERBOSE "== Checking source file updates and fips checksums"
 339
 340 make update >&42
 341 # As long as we're doing an alpha release, we can have symbols without specific
 342 # numbers assigned. In a beta or final release, all symbols MUST have an
 343 # assigned number.
 344 if [ "$next_method" != 'alpha' ]; then
 345     make renumber >&42
 346 fi
 347 make update-fips-checksums >&42
 348
 349 if [ -n "$(git status --porcelain)" ]; then
 350     $VERBOSE "== Committing updates"
 351     git add -u
 352     git commit $git_quiet -m $'make update\n\nRelease: yes'
 353     if [ -n "$reviewers" ]; then
 354         addrev --release --nopr $reviewers
 355     fi
 356 fi
 357
 358 # Create our temporary update branch, if it's not the release branch.
 359 # This is used in post-release below
 360 if $do_branch; then
 361     $VERBOSE "== Creating a local update branch: $tmp_update_branch"
 362     git branch $git_quiet "$tmp_update_branch"
 363 fi
 364
 365 # Write the version information we updated
 366 set_version
 367
 368 if [ -n "$PRE_LABEL" ]; then
 369     release="$VERSION$_PRE_RELEASE_TAG$_BUILD_METADATA"
 370     release_text="$SERIES$_BUILD_METADATA $PRE_LABEL $PRE_NUM"
 371     announce_template=openssl-announce-pre-release.tmpl
 372 else
 373     release="$VERSION$_BUILD_METADATA"
 374     release_text="$release"
 375     announce_template=openssl-announce-release.tmpl
 376 fi
 377 tag="$(std_tag_name)"
 378 $VERBOSE "== Updated version information to $release"
 379
 380 $VERBOSE "== Updating files with release date for $release : $RELEASE_DATE"
 381 for fixup in "$RELEASE_AUX"/fixup-*-release.pl; do
 382     file="$(basename "$fixup" | sed -e 's|^fixup-||' -e 's|-release\.pl$||')"
 383     $VERBOSE "> $file"
 384     RELEASE="$release" RELEASE_TEXT="$release_text" RELEASE_DATE="$RELEASE_DATE" \
 385         perl -pi $fixup $file
 386 done
 387
 388 $VERBOSE "== Committing updates and tagging"
 389 git add -u
 390 git commit $git_quiet -m "Prepare for release of $release_text"$'\n\nRelease: yes'
 391 if [ -n "$reviewers" ]; then
 392     addrev --release --nopr $reviewers
 393 fi
 394 echo "Tagging release with tag $tag.  You may need to enter a pass phrase"
 395 git tag$tagkey "$tag" -m "OpenSSL $release release tag"
 396
 397 tarfile=openssl-$release.tar
 398 tgzfile=$tarfile.gz
 399 announce=openssl-$release.txt
 400
 401 echo "== Generating tar, hash and announcement files.  This make take a bit of time"
 402
 403 $VERBOSE "== Making tarfile: $tgzfile"
 404 # Unfortunately, util/mktar.sh does verbose output on STDERR...  for good
 405 # reason, but it means we don't display errors unless --verbose
 406 ./util/mktar.sh --tarfile="../$tarfile" 2>&1 \
 407     | while read L; do $VERBOSE "> $L"; done
 408
 409 if ! [ -f "../$tgzfile" ]; then
 410     echo >&2 "Where did the tarball end up? (../$tgzfile)"
 411     exit 1
 412 fi
 413
 414 $VERBOSE "== Generating checksums: $tgzfile.sha1 $tgzfile.sha256"
 415 openssl sha1 < "../$tgzfile" | \
 416     (IFS='='; while read X H; do echo $H; done) > "../$tgzfile.sha1"
 417 openssl sha256 < "../$tgzfile" | \
 418     (IFS='='; while read X H; do echo $H; done) > "../$tgzfile.sha256"
 419 length=$(wc -c < "../$tgzfile")
 420 sha1hash=$(cat "../$tgzfile.sha1")
 421 sha256hash=$(cat "../$tgzfile.sha256")
 422
 423 $VERBOSE "== Generating announcement text: $announce"
 424 # Hack the announcement template
 425 cat "$RELEASE_AUX/$announce_template" \
 426     | sed -e "s|\\\$release_text|$release_text|g" \
 427           -e "s|\\\$release|$release|g" \
 428           -e "s|\\\$series|$SERIES|g" \
 429           -e "s|\\\$label|$PRE_LABEL|g" \
 430           -e "s|\\\$tarfile|$tgzfile|" \
 431           -e "s|\\\$length|$length|" \
 432           -e "s|\\\$sha1hash|$sha1hash|" \
 433           -e "s|\\\$sha256hash|$sha256hash|" \
 434     | perl -p "$RELEASE_AUX/fix-title.pl" \
 435     > "../$announce"
 436
 437 $VERBOSE "== Generating signatures: $tgzfile.asc $announce.asc"
 438 rm -f "../$tgzfile.asc" "../$announce.asc"
 439 echo "Signing the release files.  You may need to enter a pass phrase"
 440 gpg$gpgkey --use-agent -sba "../$tgzfile"
 441 gpg$gpgkey --use-agent -sta --clearsign "../$announce"
 442
 443 # Push everything to the parent repo
 444 $VERBOSE "== Push what we have to the parent repository"
 445 git push --follow-tags parent HEAD
 446
 447 if $do_upload; then
 448     (
 449         if [ "$VERBOSE" != ':' ]; then
 450             echo "progress"
 451         fi
 452         echo "put ../$tgzfile"
 453         echo "put ../$tgzfile.sha1"
 454         echo "put ../$tgzfile.sha256"
 455         echo "put ../$tgzfile.asc"
 456         echo "put ../$announce.asc"
 457     ) \
 458     | sftp "$upload_address"
 459 fi
 460
 461 # Post-release #######################################################
 462
 463 $VERBOSE "== Reset all files to their pre-release contents"
 464 git reset $git_quiet HEAD^ -- .
 465 git checkout -- .
 466
 467 prev_release_text="$release_text"
 468 prev_release_date="$RELEASE_DATE"
 469
 470 next_release_state "$next_method2"
 471 set_version
 472
 473 release="$VERSION$_PRE_RELEASE_TAG$_BUILD_METADATA"
 474 release_text="$VERSION$_BUILD_METADATA"
 475 if [ -n "$PRE_LABEL" ]; then
 476     release_text="$SERIES$_BUILD_METADATA $PRE_LABEL $PRE_NUM"
 477 fi
 478 $VERBOSE "== Updated version information to $release"
 479
 480 $VERBOSE "== Updating files for $release :"
 481 for fixup in "$RELEASE_AUX"/fixup-*-postrelease.pl; do
 482     file="$(basename "$fixup" | sed -e 's|^fixup-||' -e 's|-postrelease\.pl$||')"
 483     $VERBOSE "> $file"
 484     RELEASE="$release" RELEASE_TEXT="$release_text" \
 485         PREV_RELEASE_TEXT="$prev_release_text" \
 486         PREV_RELEASE_DATE="$prev_release_date" \
 487         perl -pi $fixup $file
 488 done
 489
 490 $VERBOSE "== Committing updates"
 491 git add -u
 492 git commit $git_quiet -m "Prepare for $release_text"$'\n\nRelease: yes'
 493 if [ -n "$reviewers" ]; then
 494     addrev --release --nopr $reviewers
 495 fi
 496
 497 # Push everything to the parent repo
 498 $VERBOSE "== Push what we have to the parent repository"
 499 git push parent HEAD
 500
 501 if $do_branch; then
 502     $VERBOSE "== Going back to the update branch $tmp_update_branch"
 503     git checkout $git_quiet "$tmp_update_branch"
 504
 505     get_version
 506     next_release_state "minor"
 507     set_version
 508
 509     release="$VERSION$_PRE_RELEASE_TAG$_BUILD_METADATA"
 510     release_text="$SERIES$_BUILD_METADATA"
 511     $VERBOSE "== Updated version information to $release"
 512
 513     $VERBOSE "== Updating files for $release :"
 514     for fixup in "$RELEASE_AUX"/fixup-*-postrelease.pl; do
 515         file="$(basename "$fixup" | sed -e 's|^fixup-||' -e 's|-postrelease\.pl$||')"
 516         $VERBOSE "> $file"
 517         RELEASE="$release" RELEASE_TEXT="$release_text" \
 518             perl -pi $fixup $file
 519     done
 520
 521     $VERBOSE "== Committing updates"
 522     git add -u
 523     git commit $git_quiet -m "Prepare for $release_text"$'\n\nRelease: yes'
 524     if [ -n "$reviewers" ]; then
 525         addrev --release --nopr $reviewers
 526     fi
 527 fi
 528
 529 # Push everything to the parent repo
 530 $VERBOSE "== Push what we have to the parent repository"
 531 git push parent HEAD
 532
 533 # Done ###############################################################
 534
 535 $VERBOSE "== Done"
 536
 537 cd $HERE
 538 cat <<EOF
 539
 540 ======================================================================
 541 The release is done, and involves a few files and commits for you to
 542 deal with.  Everything you need has been pushed to your repository,
 543 please see instructions that follow.
 544 ======================================================================
 545
 546 EOF
 547
 548 if $do_release; then
 549     cat <<EOF
 550
 551 The following files were uploaded to $upload_address, please ensure they
 552 are dealt with appropriately:
 553
 554     $tgzfile
 555     $tgzfile.sha1
 556     $tgzfile.sha256
 557     $tgzfile.asc
 558     $announce.asc
 559 EOF
 560 fi
 561
 562 cat <<EOF
 563
 564 ----------------------------------------------------------------------
 565 EOF
 566
 567 if $do_branch; then
 568     cat <<EOF
 569 You need to prepare the main repository with a new branch, '$release_branch'.
 570 That is done directly in the server's bare repository like this:
 571
 572     git branch $release_branch $orig_HEAD
 573
 574 Two additional release branches have been added to your repository.
 575 Push them to github, make PRs from them and have them approved:
 576
 577     $tmp_update_branch
 578     $tmp_release_branch
 579
 580 When merging them into the main repository, do it like this:
 581
 582     git push git@github.openssl.org:openssl/openssl.git \\
 583         $tmp_release_branch:$release_branch
 584     git push git@github.openssl.org:openssl/openssl.git \\
 585         $tmp_update_branch:$update_branch
 586     git push git@github.openssl.org:openssl/openssl.git \\
 587         $tag
 588 EOF
 589 else
 590 cat <<EOF
 591 One additional release branch has been added to your repository.
 592 Push it to github, make a PR from it and have it approved:
 593
 594     $tmp_release_branch
 595
 596 When merging it into the main repository, do it like this:
 597
 598     git push git@github.openssl.org:openssl/openssl.git \\
 599         $tmp_release_branch:$release_branch
 600     git push git@github.openssl.org:openssl/openssl.git \\
 601         $tag
 602 EOF
 603 fi
 604
 605 cat <<EOF
 606
 607 ----------------------------------------------------------------------
 608 EOF
 609
 610 cat <<EOF
 611
 612 When everything is done, or if something went wrong and you want to start
 613 over, simply clean away temporary things left behind:
 614
 615 The release worktree:
 616
 617     rm -rf $release_clone
 618 EOF
 619
 620 if $do_branch; then
 621     cat <<EOF
 622
 623 The additional release branches:
 624
 625     git branch -D $tmp_release_branch
 626     git branch -D $tmp_update_branch
 627 EOF
 628 else
 629     cat <<EOF
 630
 631 The temporary release branch:
 632
 633     git branch -D $tmp_release_branch
 634 EOF
 635 fi
 636
 637 exit 0
 638
 639 # cat is inconsequential, it's only there to fend off zealous shell parsers
 640 # that parse all the way here.
 641 cat <<EOF
 642 ### BEGIN MANUAL
 643 =pod
 644
 645 =head1 NAME
 646
 647 release.sh - OpenSSL release script
 648
 649 =head1 SYNOPSIS
 650
 651 B<release.sh>
 652 [
 653 B<--alpha> |
 654 B<--next-beta> |
 655 B<--beta> |
 656 B<--final> |
 657 B<--branch> |
 658 B<--local-user>=I<keyid> |
 659 B<--reviewer>=I<id> |
 660 B<--no-upload> |
 661 B<--no-update> |
 662 B<--verbose> |
 663 B<--debug> |
 664 B<--help> |
 665 B<--manual>
 666 ]
 667
 668 =head1 DESCRIPTION
 669
 670 B<release.sh> creates an OpenSSL release, given current worktree conditions.
 671 It will refuse to work unless the current branch is C<master> or a release
 672 branch (see L</RELEASE BRANCHES AND TAGS> below for a discussion on those).
 673
 674 B<release.sh> tries to be smart and figure out the next release if no hints
 675 are given through options, and will exit with an error in ambiguous cases.
 676
 677 B<release.sh> finishes off with instructions on what to do next.  When
 678 finishing commands are given, they must be followed exactly.
 679
 680 B<release.sh> leaves behind a clone of the local workspace, as well as one
 681 or two branches in the local repository.  These will be mentioned and can
 682 safely be removed after all instructions have been successfully followed.
 683
 684 =head1 OPTIONS
 685
 686 =over 4
 687
 688 =item B<--alpha>, B<--beta>
 689
 690 Set the state of this branch to indicate that alpha or beta releases are
 691 to be done.
 692
 693 B<--alpha> is only acceptable if the I<PATCH> version number is zero and
 694 the current state is "in development" or that alpha releases are ongoing.
 695
 696 B<--beta> is only acceptable if the I<PATCH> version number is zero and
 697 that alpha or beta releases are ongoing.
 698
 699 =item B<--next-beta>
 700
 701 Use together with B<--alpha> to switch to beta releases after the current
 702 release is done.
 703
 704 =item B<--final>
 705
 706 Set the state of this branch to indicate that regular releases are to be
 707 done.  This is only valid if alpha or beta releases are currently ongoing.
 708
 709 This implies B<--branch>.
 710
 711 =item B<--branch>
 712
 713 Create a branch specific for the I<SERIES> release series, if it doesn't
 714 already exist, and switch to it.  The exact branch name will be
 715 C<< openssl-I<SERIES> >>.
 716
 717 =item B<--no-upload>
 718
 719 Don't upload the produced files.
 720
 721 =item B<--no-update>
 722
 723 Don't run C<make update> and C<make update-fips-checksums>.
 724
 725 =item B<--verbose>
 726
 727 Verbose output.
 728
 729 =item B<--debug>
 730
 731 Display extra debug output.  Implies B<--no-upload>
 732
 733 =item B<--local-user>=I<keyid>
 734
 735 Use I<keyid> as the local user for C<git tag> and for signing with C<gpg>.
 736
 737 If not given, then the default e-mail address' key is used.
 738
 739 =item B<--reviewer>=I<id>
 740
 741 Add I<id> to the set of reviewers for the commits performed by this script.
 742 Multiple reviewers are allowed.
 743
 744 If no reviewer is given, you will have to run C<addrev> manually, which
 745 means retagging a release commit manually as well.
 746
 747 =item B<--force>
 748
 749 Force execution.  Precisely, the check that the current branch is C<master>
 750 or a release branch is not done.
 751
 752 =item B<--help>
 753
 754 Display a quick help text and exit.
 755
 756 =item B<--manual>
 757
 758 Display this manual and exit.
 759
 760 =back
 761
 762 =head1 RELEASE BRANCHES AND TAGS
 763
 764 Prior to OpenSSL 3.0, the release branches were named
 765 C<< OpenSSL_I<SERIES>-stable >>, and the release tags were named
 766 C<< OpenSSL_I<VERSION> >> for regular releases, or
 767 C<< OpenSSL_I<VERSION>-preI<n> >> for pre-releases.
 768
 769 From OpenSSL 3.0 ongoing, the release branches are named
 770 C<< openssl-I<SERIES> >>, and the release tags are named
 771 C<< openssl-I<VERSION> >> for regular releases, or
 772 C<< openssl-I<VERSION>-alphaI<n> >> for alpha releases
 773 and C<< openssl-I<VERSION>-betaI<n> >> for beta releases.
 774
 775 B<release.sh> recognises both forms.
 776
 777 =head1 VERSION AND STATE
 778
 779 With OpenSSL 3.0, all the version and state information is in the file
 780 F<VERSION.dat>, where the following variables are used and changed:
 781
 782 =over 4
 783
 784 =item B<MAJOR>, B<MINOR>, B<PATCH>
 785
 786 The three part of the version number.
 787
 788 =item B<PRE_RELEASE_TAG>
 789
 790 The indicator of the current state of the branch.  The value may be one pf:
 791
 792 =over 4
 793
 794 =item C<dev>
 795
 796 This branch is "in development".  This is typical for the C<master> branch
 797 unless there are ongoing alpha or beta releases.
 798
 799 =item C<< alphaI<n> >> or C<< alphaI<n>-dev >>
 800
 801 This branch has alpha releases going on.  C<< alphaI<n>-dev >> is what
 802 should normally be seen in the git workspace, indicating that
 803 C<< alphaI<n> >> is in development.  C<< alphaI<n> >> is what should be
 804 found in the alpha release tar file.
 805
 806 =item C<< alphaI<n> >> or C<< alphaI<n>-dev >>
 807
 808 This branch has beta releases going on.  The details are otherwise exactly
 809 as for alpha.
 810
 811 =item I<no value>
 812
 813 This is normally not seen in the git workspace, but should always be what's
 814 found in the tar file of a regular release.
 815
 816 =back
 817
 818 =item B<BUILD_METADATA>
 819
 820 Extra build metadata to be used by anyone for their own purposes.
 821
 822 =item B<RELEASE_DATE>
 823
 824 This is normally empty in the git workspace, but should always have the
 825 release date in the tar file of any release.
 826
 827 =back
 828
 829 =head1 COPYRIGHT
 830
 831 Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.
 832
 833 Licensed under the Apache License 2.0 (the "License").  You may not use
 834 this file except in compliance with the License.  You can obtain a copy
 835 in the file LICENSE in the source distribution or at
 836 L<https://www.openssl.org/source/license.html>.
 837
 838 =cut
 839 ### END MANUAL
 840 EOF