Release Instructions and Checklist

Introduction

This page include detailed instructions on how to create a release but also serves as a page to follow up on plans and progress for upcoming releases

Note: This page currently focus on releases from master branch, which from 2023-10-01 only will be used for major releases. Minor releases will be managed from a branch <major>.X, like 4.x. This page does not yet fully reflect that.

Related issues/PRs for reference

Status of upcoming releases

V5.0

Planned October 2024 Release candidate created

V4.2

May 2024

V4.1

Official Release 2023-12-22

V4.0

Official Release 2023-05-22

V3.1.1

Released: 2023-03-01

V3.1

Released: 2023-02-24

V3.0

Released 2022-08-09

Instructions on how to create a release

Create a checklist for the planned release

Add a TODO list and copy the checklist from an old release, put them at top of this document. Checklists for older release can be removed.

Decide on PRs, which should be included

This concerns pull requests for both vehicle_signal_specification and vss-tools repositories. This is typically discussed and agreed in the weekly VSS meetings. Update the TODO list.

Decide on version number to use

VSS intend to use PEP compliant version numbers. For versions to be released further limited by versions supported by PyPI.

X.Y or X.Y.Z - A released version.
X.Y.devN, N starting from 0 - Developer builds - normally not published to PyPI.
X.YaN, N starting from 0 - Pre-releases, may be published to PyPI if needed for testing purposes.
X.YrcN, N starting from 0 - Release candidates, to be published around two weeks before a major/minor release.

Versions are typically named as X.Y.Z where X is major version, Y minor version and Z patch version. In many cases only X.Y is used if Z is 0. General approach is to use (X+1).0 if there are major additions or major changes causing incompatibility, otherwise use X.(Y+1). A draft version number (e.g. X.Y.dev0) shall already be in use on master branch, and it must be decided if that number shall be used for the release (i.e. only remove -develop) or if a different number shall be used.

Create release branch

To avoid "locking" the master branch, it is recommended to prepare the release in a release/X.Y branch (for both vss and vss-tools). When finished relevant parts shall be merged back to master or relevant maintenance branch.

Remaining work can be performed in release branch

Remove deprecated content

If preparing a major release (i.e. X.0) then all code/content/signals that has been marked as deprecated within previous releases shall be removed. Search for deprecation:in *.vspec files. Also search for deprecation/deprecated in documentation and tools.

Update CHANGELOG

For both VSS and VSS-tools repo, update CHANGELOG file with noteworthy changes

Update VSS-tools version

Change version in pyproject.toml, typically to a RC version like 4.1rc0 See https://github.com/COVESA/vss-tools/wiki/PyPI-packing

Upload directly to the release/X.Y branch or create a pull request.

Update poetry.lock by doing poetry lock

You can also (preferably) create and upload a release candidate to PyPI already now, see instructions. Verify that it exists on pypi. If you create a pypi release also upload corresponding tag to github repo for traceability (no v as prefix.).

Update tools on main repository

This is currently performed by changing scripts/install_vss_tools.sh. This can be performed first when all pull requests intended for vss-tools for this release have been merged.

Note that this may change!

Remember to change back to "master" when merging back

Update `VERSION` file in master branch

No longer used!

Update default version in spec

Update default values for signals in branch VersionVSS in file spec/Vehicle/Vehicle.vspec. For VersionVSS.Labelthere shall be no default value for released versions. For pre-releases default: 'dev' shall be used.

No reason to include rcN suffix here

An example is shown below.

VersionVSS.Major:
  datatype: uint32
  type: attribute
  default: 3
  description: Supported Version of VSS - Major version.

VersionVSS.Minor:
  datatype: uint32
  type: attribute
  default: 0  
  description: Supported Version of VSS - Minor version.

VersionVSS.Patch:
  datatype: uint32
  type: attribute
  default: 0
  description: Supported Version of VSS - Patch version.

VersionVSS.Label:
  datatype: string
  type: attribute
  default: ''
  description: Label to further describe the version.

Update version in html documentation

The generated documentation mentions latest released version:

This is updated by changing version number after Latest Released Version: in docs-gen/layouts/partials/menu-footer.html

No reason to include rcN suffix here

For minor releases it can be updated, but does not necessarily needs to be merged back to master!

Update remote/official branch with changes

Create commit, upload to fork of vehicle_signal_specification repository. Create pull request. Review and Merge

(Now make sure that no other commits are merged before tagged)

Check links in *.md files and generated documentation

This is to verify that there are no dead links, see file.

(Not necessary for minor release)

Perform Testing

Run at least all tools from Makefile and verify that changes (if any) are as expected.

Compare output with base release (do a diff)

Create version tag (for both VSS and VSS-Tools)

Can be performed locally and pushed to official VSS repository. Example below based on assumption that https://github.com/COVESA/vehicle_signal_specification is referenced by the remote upstream.

(For release candidate vX.YrcN, where N starts with 0)

For vss start with v, for vss-tools start with number

git tag v3.0
git push upstream v3.0

VSS

For VSS it is recommended to trigger a build of a draft release, that will automatically create a tag. Then give number without v, a v will anyway be appended when tagging.

Another example

Tagging will be performed when release is published.

Create Github Release

This assumes that you have run the "Create Draft Release" action

Draft release notes

Use the draft release you have created
Select release branch and previous tag and click Generate release notes. For minor releases no pull-requests will be presented
Remove the ## New Contributors section if present.
Set as pre-release if rc, otherwise latest
Add a section ## Changes with this release on top - Possibly take content from CHANGELOG.md

Template:

## Changes with this release:
### Change 1
### Change 2

*See [VSS CHANGELOG](https://github.com/COVESA/vehicle_signal_specification/blob/master/CHANGELOG.md) and [VSS-Tools CHANGELOG](https://github.com/COVESA/vss-tools/blob/master/CHANGELOG.md) for more information. For complete list of commits see below.*

Sanity check of artifacts - verify that content is as expected

Compare with previous releases

Publish release

If everything looks as expected, possibly after review by VSS colleagues, edit the release and publish it.

Branch off to release branch

Unless you already have done this!*

Changing from rc to real release (or create new rc)

Idea is that after release candidate has been released, any changes for the release shall be directed to the release branch (like release/4.0).

What to do:

Check if there are new PRs
Update version where needed
- vss-tools : pyproject.toml
Create new pypi release
Create and upload new tags
Create new release
- Update vss-tools dependency
Upload/Replace "high level" tag, like v5pointing to latest v5.X tag/release

Make sure to include new artifacts, and copy release note text if need

Create release/maintenance branch (for both VSS and VSS-Tools)

*New process *

Create a branch release/X.Y or release/X.Y.Z (when Z>0) for release candidates of major versions. That prevents the need to "lock" master branch during rc evaluation.
When a major release is created add a branch for future minor releases, like if 5.0 is released add 5.X

For vss repo, never delete the release branch, needed by some downstream projects

Tag `vss-tools`

NOTE: Tags for vss-tools must now follow pypi format, like X.Y or X.Yrc0 Github releases does not include submodules. Even if a vss-tools versions indirectly are given by the tag in vss repo, it might be helpful to create a tag also in vss-tools, to make it easier to see which vss-tools versions that is used by each vss version.

General idea (for now), tag and create a branch for fixes, if needed:

git push upstream master:release/3.0
git tag v3.0
git push upstream v3.0

Prepare for next release (e.g. update version)

The last step is to prepare the master branch for new pull requests. If release version was 3.0, then a possible identifier for next release in code could be 3.1-dev (no trailing 0 for master)

Update default values for signals in branch VersionVSS in file spec/Vehicle/Vehicle.vspec. Do not forget to add default: 'dev'

Run the tools - for example make csv and verify that the file name reflects version and the version signals are updated.

Create a pull request, if needed have it reviewed and then merge it to master. After this everything is done and master branch is "unlocked" for merging new pull requests.

Change to new version in vss-tools pyproject.toml file

Should be of this form (to comply with PyPI rules): version ='4.1.dev0'

Wait 2 weeks

Create official release

This includes:

Tag a new version in vss-tools, typically to an official version like 4.1, see https://github.com/COVESA/vss-tools/wiki/PyPI-packing, and upload a new release.

Tag with official version, update vss-tools reference, create new release.

Make sure to create and upload a new vss-tools pypi release, see

Upload official pypi vss-tools package

Tag and upload new package as described in https://github.com/COVESA/vss-tools/wiki/PyPI-packing

Merge/Cherry-pick relevant changes (if any) from release branch back to master

If merging make sure that you get "right versions". Make sure to use new vss-tools.

Make sure that correct version numbers remain after merge

Update vss-tools compatibility information tests

Add released version to https://github.com/COVESA/vss-tools/blob/master/tests/backward_compatibility/test_compatibility.py
Update https://github.com/COVESA/vss-tools/blob/master/README.md#compatibility-with-vss to include latest VSS and VSS-tools version

Checklist VSS release Template

Workflow for fixing errors in a release

If important errors are found shortly after tagging or possibly even after releasing it is possible to

Update release notes
Delete a release and create a new one as described below
Create a local branch based on the release/X.Y branch
Perform the changes needed
git push upstream mybranch:release/3.0
git tag --force v3.0
git push --force upstream v3.0
(Re-)create the release, if it previously was removed

Otherwise create a patch release, let release notes contain only changes from previous release, e.g. compare 3.1.1 with 3.1.0

Patch release

Patch releases can typically be performed using the base release/X.Y branch.

Post-release cleanup

6 months after the release the release candidate tags may be deleted