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