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

Add a upcoming release to wiki page Smart Card Release Testing
Create a tracking issue with proposed changelog for NEWS, for example Towards new release 0.22.0

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!
configure.ac : 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.
.appveyor.yml: Update the version on first line
README.md: Update the links to the new release and binaries
SECURITY.md: Update supported version

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

Build and Test Binaries

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
```
Prepare build artifacts
- Wait around 30-50 minutes (after pushing the tag) to allow build artifacts be placed into the Nightly Builds
- All builds must succeed and must not generate more warnings than the previous build.
- Copy build artifacts selecting the correct branch using the hash of the release commit, e.g.
```
git clone https://github.com/OpenSC/OpenSC --single-branch
cd OpenSC
BRANCH=`git log --max-count=1 --date=short --abbrev=8 --pretty=format:"%cd_%h"`
wget https://github.com/OpenSC/Nightly/archive/${BRANCH}.zip
unzip ${BRANCH}.zip
```
- Recreate the macOS image and Windows Debug files
```
cat OpenSC*.dmg.* > OpenSC-0.XX.0.dmg
cat OpenSC-*_win64-Debug.zip.* > OpenSC-0.XX.0_win64-Debug.zip
```
- For final releases, download signed Windows installers from Signpath.io instead of unsigned installers from AppVeyor (i.e. Nightly builds):
  1. Navigate to Signpath's outstanding Signing Requests
  2. Select the ones that were issued with the creation of the release branch
  3. Check the signing request's Build data URL to match the related AppVeyor build that was triggered with creation of the release branch
  4. Approve signing and wait for completion of the signing process
  5. Download signed artifact from Signpath.io
- 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

Create new branch from last release tag

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

Add commits with fixes
- Use git cherry-pick -x to pick commits from master to reference commit hashes

Remove suffixes from build names in appveyor.yml and .github/build.sh script

diff --git a/.appveyor.yml b/.appveyor.yml
index 4599100ad2..bca1775ae3 100644
--- a/.appveyor.yml
+++ b/.appveyor.yml
@@ -96,8 +96,7 @@ build_script:
      }
  - bash -c "exec 0</dev/null && if [ \"$APPVEYOR_REPO_BRANCH\" == \"master\" -a -z \"$APPVEYOR_PULL_REQUEST_NUMBER\" ]; then ./bootstrap; fi"
  - bash -c "exec 0</dev/null && if [ \"$APPVEYOR_REPO_BRANCH\" == \"master\" -a -n \"$APPVEYOR_PULL_REQUEST_NUMBER\" ]; then ./bootstrap.ci -s \"-pr$APPVEYOR_PULL_REQUEST_NUMBER\"; fi"
-  - bash -c "exec 0</dev/null && if [ \"$APPVEYOR_REPO_BRANCH\" != \"master\" -a -z \"$APPVEYOR_PULL_REQUEST_NUMBER\" ]; then ./bootstrap.ci -s \"-$APPVEYOR_REPO_BRANCH\"; fi"
-  - bash -c "exec 0</dev/null && if [ \"$APPVEYOR_REPO_BRANCH\" != \"master\" -a -n \"$APPVEYOR_PULL_REQUEST_NUMBER\" ]; then ./bootstrap.ci -s \"-$APPVEYOR_REPO_BRANCH-prAPPVEYOR_PULL_REQUEST_NUMBER\"; fi"
+  - bash -c "exec 0</dev/null && if [ \"$APPVEYOR_REPO_BRANCH\" != \"master\" ]; then ./bootstrap; fi"
  # disable features to speed up the script
  - bash -c "exec 0</dev/null && ./configure --with-cygwin-native --disable-openssl --disable-readline --disable-zlib || cat config.log"
  - bash -c "exec 0</dev/null && rm src/getopt.h"
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>

Both in stable-0.X.[Y+1] and master branch:
- update version in .appveyor.yml,
- update NEWS with changes,
- update version in SECURITY.md,
- update version and LT revision in configure.ac.
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
```
Wait for artifacts to build
Create a new release
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

There are two access tokens that are used by CI to push artifacts to the Nightly repository. One from Github Actions and one from AppVeyor. Their expiration can be checked on the organization settings page.

When they expire, the new need tokens need to be generated in user settings.
Both tokens need 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.
The AppVeyor token needs to be encrypted using AppVeyor website and updated in the .appveyor.yml for example like done in #3230.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenSC-Release-Howto.md

OpenSC-Release-Howto.md

OpenSC Release Howto

Generic Principles

Preparing Security Relevant Changes

Release Preparations

On Github

In Version Control (git)

Build and Test Binaries

Create release

Announcement

Releasing patch versions of OpenSC

How to do it

Maintenance tasks

Clean up old nightly builds repository

Refreshing access tokens

Files

OpenSC-Release-Howto.md

Latest commit

History

OpenSC-Release-Howto.md

File metadata and controls

OpenSC Release Howto

Generic Principles

Preparing Security Relevant Changes

Release Preparations

On Github

In Version Control (git)

Build and Test Binaries

Create release

Announcement

Releasing patch versions of OpenSC

How to do it

Maintenance tasks

Clean up old nightly builds repository

Refreshing access tokens