Skip to content

Release Instructions and Checklist

Jump to bottom Edit New page
Erik Jaegervall edited this page Feb 24, 2023 · 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: Check this discussion

V5.0

Possible date: End of October 2023 (Fall AMM)

V4.0

Target date: End of April 2023 (Spring AMM)

V3.1

Released: 2023-02-24

Checklist

  • Create a checklist for the planned release
  • Remove deprecated content -N/A
  • Decide on PRs, which should be included
  • Decide on version number to use
  • Update CHANGELOG
  • 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
  • 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)

V3.0

Released 2022-08-09

Checklist VSS release

  • Create a checklist for the planned release
  • Remove deprecated content
  • Decide on PRs, which should be included
  • Decide on version number to use
  • 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
  • Create version tag
  • Create output artifacts
  • Create Github Release
  • Create release/maintenance branch
  • Tag vss-tools
  • Prepare for next release (e.g. update version)

V2.2

Checklist VSS release

  • Decide on PRs, which should be included
  • Decide on version (breaking changes introduced?)
  • Update tools on main repository
  • Update VERSION file in master branch
  • Update default version in spec
  • Update version in html documentation
  • Branch off to release branch
  • Create log history since last release
  • Draft release notes
  • Create serialised files
  • Create version tag
  • Publish in github, incl. files, documentation, release notes & history

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

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-develop) shall already be in use on masterbranch, 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 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
  • X.Y-develop for ongoing work intended to be released as X.Y in master branch

In most cases this step involves changing X.Y-develop to X.Y

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: 'develop' shall be used. 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
  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

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)

Perform Testing

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

Create version tag

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.

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.
  • Add summary and outcome sections at top

Attach binaries

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

Attach *.json and *.tar.gz files. The reason for the *.json file to be included both explicitly and in the *.tar.gz file is to simplify the usage of the JSON file in online JSON editors.

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.

image

Publish release

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

  • Branch off to release branch

Create release/maintenance branch

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

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:

  • 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-develop

  • 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: 'develop'

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: version ='3.1.dev+' + r.stdout.rstrip().decode('UTF-8')

Note: COVESA does not publish any package to e.g. PyPI so no need to have a version without dev here. If we would publish to PyPI then we would need to build and publish at least once without dev suffix

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 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
  • 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)

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