Skip to content

OpenSC-Release-Howto.md

Latest commit

 

History

History
173 lines (132 loc) · 8.46 KB

OpenSC-Release-Howto.md

File metadata and controls

173 lines (132 loc) · 8.46 KB
Raw

OpenSC Release Howto

Releasing OpenSC should be simple and streamlined, yet a predictable and easily repeatable process. This page describes releasing OpenSC from Git.

Generic Principles

  • At least one (or more, if needed) pre-releases must be done before the actual release.
  • After a release candidate has been published, no more merges to the master branch should happen, only release-critical single commits can be cherry-picked and a new release candidate created.
  • Normal development should continue when the final release is done.
  • OpenSC usually does not release micro updates for previously released versions
    • Micro updates happen in rare occasions when fixing more critical issues

Preparing Security Relevant Changes

  • Request a CVE in case of security relevant fixes or changes.
    • Use Red Hat product security at secalert@redhat.com describing the CVE and ask for CVE allocation.
      • Do NOT use mitre directly as their response times are terrible.
    • Filter OSS-Fuzz for security relevant issues that were fixed for this release
    • Filter Coverity scan for High impact issues that were fixed for this release
  • Update the security advisories
  • Mention CVE ID in the NEWS file

Release Preparations

On Github

In Version Control (git)

Release (or RC) version must be changed in the following files:

  • NEWS: Make sure to fix the release date for final release!
  • VERSION.mk : change package version major/minor/fix as needed, RCs get the package suffix -rc, which is removed for the final release
  • configure.ac : Update the LT version number, which is required with changes to, for example, opensc.h and libopensc.exports.
  • packaging/opensc.spec: Update the version number to match VERSION.mk
  • SECURITY.md: Update supported version

Optionally, discuss changes to NEWS by opening a new issue with your suggestions.

Build and Test Binaries

  1. Create release tag

    • Lightweight tag for release candidate

      • Via GitHub when creating release - GitHub will automatically create *-rcX as lightweight tag

      • Locally with git

        git tag 0.20.0
git push origin 0.20.0

    • Annotated tag for final release

      • Locally with git

        git tag -a 0.20.0
git push origin 0.20.0

  2. Prepare build artifacts

    • Wait around 30-50 minutes (after pushing the tag) to allow build artifacts to be built

    • All builds must succeed and must not generate more warnings than the previous build.

    • Download signed MacOS installers from GH Actions (use the artifact opensc-build-macos-15 from the OSX pipeline)

    • Download signed Windows installers from Signpath.io:

      1. Navigate to Signpath's outstanding Signing Requests
      2. Select the ones that were issued with the creation of the release tag
      3. Check the signing request's commit ID (under repository data) matches the commit pointed by release tag
      4. Approve signing and wait for completion of the signing process
      5. Download signed artifact from Signpath.io and extract them from zip archives

    • Download debug zip archives for Windows from github artifacts (names matching the MSI from signpath with -dbg suffix)

    • Do a separate smoke test for all installers and the tarball, document your results in the Wiki.

Create release

  • A new (draft) release is created via button on the release page
  • Describe the release including all changes to NEWS (Markdown)
  • Select appropriate tag (when pushed before) or create new one in GitHub (for lightweight tags only)
    • For final releases, select the existing tag, e.g. 0.20.0; for release candidates choose a new tag, e.g. 0.20.0-rc1
  • Upload the build artifacts to the new release
    • From Nightly Builds: Release tarball, OSX installer, 2 variants (default, light) of Windows separate debug archives for both 64b and 32b
    • From Signpath.io: 2 variants (default, light) of Windows installer for both 64b and 32b
  • Check:
    • This is a pre-release if only creating a release candidate
    • Set as latest release if creating final release

Announcement

  • Write announcement, short human readable version
    • Short overview of OpenSC
    • Important and visible (breaking) changes in this release (not a copy of NEWS file)
    • URL-s for downloads
    • Pointers to full verbose information (list of commits, full changelog, closed bugs)
    • SHA-256 hashes of release artifacts (openssl sha256 or sha256sum)
    • Plans for next release
  • Find someone to proofread the announcement.
  • Via mail publish the announcement on opensc-announce@lists.sourceforge.net and opensc-devel@lists.sourceforge.net lists.
  • In case of security relevant changes, forward the announcement to oss-security@lists.openwall.com
  • Update the Main Wiki page with links to new release

Releasing patch versions of OpenSC

  • Happens on exceptional basis only when fixing significant problems.
  • Release contains only fixup commits on top of previous minor/major release.
  • Discuss whether changes need another round of testing.

How to do it

  1. Create new branch from last release tag

    git checkout -b stable-0.X.[Y+1] tags/0.X.Y

  2. Add commits with fixes

    • Use git cherry-pick -x to pick commits from master to reference commit hashes

  3. Remove suffixes from build names in .github/build.sh script

    diff --git a/.github/build.sh b/.github/build.sh
index 7770590af1..afb58af450 100755
--- a/.github/build.sh
+++ b/.github/build.sh
@@ -15,11 +15,6 @@ if [ "$GITHUB_EVENT_NAME" == "pull_request" ]; then
  else
    SUFFIX="$GITHUB_BASE_REF-pr$PR_NUMBER"
  fi
-else
-	BRANCH=$(echo $GITHUB_REF | awk 'BEGIN { FS = "/" } ; { print $3 }')
-	if [ "$BRANCH" != "master" ]; then
-		SUFFIX="$BRANCH"
-	fi
fi
if [ -n "$SUFFIX" ]; then
  ./bootstrap.ci -s "$SUFFIX" </code></pre>

  4. Both in stable-0.X.[Y+1] and master branch:

    • update NEWS with changes,
    • update version in SECURITY.md,
    • update version and LT revision in configure.ac.

  5. Push release tag 0.X.[Y+1] into stable-0.X.[Y+1] branch

    git tag -a 0.25.1
git push origin 0.25.1

  6. Wait for artifacts to build

  7. Create a new release

  8. Write announcement

Maintenance tasks

Clean up old nightly builds repository

  • The repository OpenSC/Nightly is used to hold nightly builds for both MacOS and Windows.
  • They are pushed on every master commit so the old builds need to be cleaned up regularly.
  • Ideally after the new release is done, any old branch before last release can be removed through the github web UI on OpenSC/Nightly/branches/stale.
  • For more info, see the related issues

Refreshing access tokens

From Github Actions, there is one access token that is used by CI to push artifacts to the Nightly repository.Its expiration can be checked on the organization settings page.

  • When it expires, the new token needs to be generated in user settings.
  • The token needs Read and Write access to code and Read access to metadata in OpenSC/Nightly repository.
  • The Github Actions token needs to be inserted into the OpenSC repository secrets.