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 releaseas. Minor releases will be managed from a branch <major>.X, like 4.x. This page does not yet fully reflect that.

Note: Check this discussion

Status of upcoming releases

V5.0

Possible date: Spring 2024

• Not much new content yet not part of or planned for 4.1

V4.1

Possible date: Late 2023 (October-December)

• Waiting for some minor features like UUID, JSONSchema, unexpanded JSON

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.

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 setup.py, typically to a RC version like 4.1rc0 See https://github.com/COVESA/vss-tools/wiki/PyPI-packing

You can also create and upload a release candidate to PyPI already now, see instructions

Update tools on main repository

This can be performed first when all pull requests intended for vss-tools for this release have been merged.

git submodule update --init
cd vss-tools
git fetch origin
git checkout origin/master
cd ..
git add vss-tools
git commit

Update VERSION file in master branch

The naming scheme typically used is:

• X.Y for offical releases (or X.Y.Z if Z != 0)
• X.Ydev for ongoing work intended to be released as X.Y in master branch

In most cases this step involves changing X.Ydev to X.Y

No reason to include rcN suffix here

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

Update master 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.

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)

git tag v3.0
git push upstream v3.0

Create output artifacts

Create files to be uploaded

(In the past output files were included in a *.tar.gz file - now individually uploaded)

make travis_targets

Verify that the following files exist (number/label may vary).

vss_rel_3.1.csv
vss_rel_3.1.graphql.ts
vss_rel_3.1.idl
vss_rel_3.1.fidl
vss_rel_3.1.json
vss_rel_3.1.yaml

Create Github Release

Draft release notes

• Use the github UI at https://github.com/COVESA/vehicle_signal_specification/releases/new to draft a new release.
• Choose the tag you already have created (e.g. v3.0).
• Use the tag name as release name.
• Select previous tag and click Generate release notes.
• Remove the ## New Contributors section if present.
• Set as pre-release if rc, otherwise latest
• Add summary (but possibly not outlook) sections at top

Template:

## Major 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.*

Attach binaries

Attach the following files:*.json, *.fidl, *.yaml, *.csv, *.graphql.ts, *.idl

Also add units.yaml? TODO: Also add no-expand for JSON

See https://github.com/COVESA/vehicle_signal_specification/issues/616

Save draft and review

Save the release as draft, then check the release at https://github.com/COVESA/vehicle_signal_specification/releases. Verify that 8 assets exist (6 manually added, 2 automatically created) and that they seem to be as expected.

Publish release

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

• Branch off to release branch

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
• Create and upload new tags
• Create new 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 (draft)

• Use a temporary branch X.Yrc for release candidates. That prevents the need to "lock" master/X.Y 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

Old process below

For each major and minor release a branch on https://github.com/COVESA/vehicle_signal_specification is created. The format release/X.Y is used. This is to simplify for users who prefer to fetch latest release based on a specific major/minor version by branch instead of tag. The branch could possibly also be used for patches, i.e. pull requests intended for 3.0.1 can be merged to the branch release/3.0.

git push upstream master:release/3.0

Use branch /X.Y even for release candidates

Tag vss-tools

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:

TODO: Evaluate if release-branch is actually needed TODO: Possibly tag/retag on all levels, i.e. create v5, v5.0 and v5.0.0

• 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 VERSION file in master branch.
• 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 setup.py file

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

Wait 2 weeks

Create official release

This includes:

Change version in setup.py, 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 submodule reference, create new release.

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

Upload official pypi vss-tools package

Change version in setup.py 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

Checklist VSS release Template

• Create a checklist for the planned release
• Remove deprecated content
• Decide on PRs, which should be included
• Decide on version number to use
• Update CHANGELOG
• Update VSS-tools version
• Update tools on main repository
• Update VERSION file in master branch
• Update default version in spec
• Update version in html documentation
• Update master branch with changes
• Check links in *.md files and generated documentation
• Perform Testing
• Create version tag
• Create output artifacts
• Create Github Release
• Create release/maintenance branch
• Tag vss-tools
• Prepare for next release (e.g. update version)
• Wait 2 weeks
• Create official release
• Merge/Cherry-pick relevant changes (if any) from release branch back to master

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