-
Notifications
You must be signed in to change notification settings - Fork 170
Release Instructions and Checklist
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
Possible date: End of October 2023 (Fall AMM)
Target date: May 2023 RC created: https://github.com/COVESA/vehicle_signal_specification/releases/tag/v4.0rc0
- 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
- 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
Released: 2023-03-01
Released: 2023-02-24
Released 2022-08-09
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.
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.
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.
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.
For both VSS and VSS-tools repo, update CHANGELOG file with noteworthy changes
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
The naming scheme typically used is:
-
X.Y
for offical releases (orX.Y.Z
ifZ != 0
) -
X.Ydev
for ongoing work intended to be released asX.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 values for signals in branch VersionVSS
in file spec/Vehicle/Vehicle.vspec
.
For VersionVSS.Label
there 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.
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
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)
This is to verify that there are no dead links, see file.
Run at least all tools from Makefile and verify that changes (if any) are as expected.
Compare output with base release (do a diff)
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 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
- 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 the following files:*.json
, *.fidl
, *.yaml,
.csv,
.graphql.ts,
*.idl`
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.
If everything looks as expected, possibly after review by VSS collagues, edit the release and publish it.
- Branch off to release branch
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
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
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
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 filespec/Vehicle/Vehicle.vspec
. Do not forget to adddefault: '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 ='3.1dev+' + 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
- 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
- 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
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