Creating a VSS Pull Request

This is a tutorial on how to create a VSS Pull Request to introduce two new signals. It is based on current master as of 2024-08-07 (planned 5.0), if using an older VSS version there would be minor changes. Examples are based on a Debian VM. Note that this is just an example, there are other ways to do it as well.

Create a fork of VSS

You must have a github account. Either create a personal fork or a fork using some other github organization where you have sufficient access. In this tutorial we use https://github.com/erikbosch/vehicle_signal_specification as an example of a private fork

Clone it and add official repo as upstream

erik@debian6:/tmp$ git clone https://github.com/erikbosch/vehicle_signal_specification
Cloning into 'vehicle_signal_specification'...
...

To be able to easily rebase on updates you may want to add official repo as another remote. This is not strictly necessary, as you can sync master branch on your fork with latest changes in the web UI as well

erik@debian6:/tmp$ cd vehicle_signal_specification/
erik@debian6:/tmp/vehicle_signal_specification$ git remote add upstream https://github.com/COVESA/vehicle_signal_specification
erik@debian6:/tmp/vehicle_signal_specification$ git fetch upstream
remote: Enumerating objects: 12174, done.
...
erik@debian6:/tmp/vehicle_signal_specification$ 

Create a branch to work on

Example below if you intend to update the master branch of you fork in the Web UI. If using a ùpstreamremote you could also create the branch from upstream/master`

erik@debian6:/tmp/vehicle_signal_specification$ git checkout -b erik_mywork origin/master
branch 'erik_mywork' set up to track 'origin/master'.
Switched to a new branch 'erik_mywork'

Do your changes

For new signals identify a good location for them and do the changes in your favorite editor

Pre-commit

To avoid erros in continuous integration you may want to install pre-commit to check line endings and similar before commit

pip install pre-commit
pre-commit install

Test it

Install tooling with pypi (right now --preis needed) and run some of the tools. Possibly take help of the Makefile

erik@debian6:/tmp/vehicle_signal_specification$ pip install --pre vss-tools
...

erik@debian6:/tmp/vehicle_signal_specification$ make csv
vspec export csv -u ./spec/units.yaml --strict -s ./spec/VehicleSignalSpecification.vspec -o vss_rel_$(cat VERSION).csv
[09:26:02] INFO     Added 30 quantities from /tmp/vehicle_signal_specification/spec/quantities.yaml                               __init__.py:895
           INFO     Added 63 units from spec/units.yaml                                                                           __init__.py:930
           INFO     Loading vspec from spec/VehicleSignalSpecification.vspec...                                                       utils.py:89
[09:26:03] INFO     Check type usage                                                                                              __init__.py:117
           INFO     Generating CSV output...                                                                                       vss2csv.py:134
erik@debian6:/tmp/vehicle_signal_specification$ 

Alternative install of vspec

Do git submodule update --init and then in vss-tools build from source

Add, commit and push

Something like

git status
git add .
git commit -s
git push origin erik_mywork

Create PR in WebUI

Verify that the changes you want is included, create a PR. You can select "Draft" first until you have verified that everything builds as expected

Wait for checks

Fix errors, and push again. For some errors you must modify the existing PR (git commit --amend) and force push.

git push -f origin erik_mywork

If everything works you should get no errors

Note

As new committer Continuous Integration may not run automatically, a VSS maintainer must trigger the build. As a work-around for testing you may run actions manually in your own fork or create a dummy PR in your own fork. For this you may need to enable actions for your fork.