Skip to content

Release Instructions and Checklist

Jump to bottom Edit New page
Erik Jaegervall (Jägervall) edited this page Jul 29, 2024 · 39 revisions

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

Possible date: Fall 2024

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

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. When finished relevant parts shall be merged back to master.

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

This is now done by tagging, no file to update!

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.Y-dev for ongoing work intended to be released as X.Y in master branch

In most cases this step involves changing X.Y-dev 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:

image

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

Create output artifacts

Create files to be uploaded

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

make mandatory_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. 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 summary (but possibly not outlook) sections at top
  • Use ## Major Changes with this release for major (X.0) release
  • Use ## Changes with this release for minor release (X.Y), Y!=0
  • Possibly take content from CHANGELOG.md

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, *.jsonschema, *_noexpand.json, *.fidl, *.yaml, *.csv, *.graphql.ts, *.idl

units.yaml quantitities.yaml

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 12 assets exist (10 manually added (8 generated, 2 static), 2 automatically created) and that they seem to be as expected.

image

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 *

  • 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

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

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

No need to change version in vss-tools as it is managed through git tags. Possibly we can use an alpha version like 5.0.0a0 rather than 4.2to make it more clear what version that is basis! 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:

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 submodule 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

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

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
Add a custom footer
Clone this wiki locally