diff --git a/BUILD.md b/BUILD.md index 17f7cef0..d64969c1 100644 --- a/BUILD.md +++ b/BUILD.md @@ -23,7 +23,7 @@ can be used successfully with tools used in continuous integration. For detailed information on development environment and usage see [VSS-Tools](https://github.com/COVESA/vss-tools). -### Set up you development environment +### Set up your development environment You are free to use whatever development environment you want, but tools in [VSS-tools](https://github.com/COVESA/vss-tools) have typically been tested only on Linux, and in continuous integration "ubuntu-latest" is used for testing. @@ -60,7 +60,7 @@ vss_rel_4.1-dev.csv ### Make sure that your changes pass CI checks Continuous Integration (CI) checks are defined in the [workflows](.github/workflows) folder. -They consist of the following areas +They consist of the following areas. #### Signoff All commits must be signed-off, see [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/CHANGELOG.md b/CHANGELOG.md index 432ed93f..a42dd8a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,12 @@ # VSS Changelog -The intention of this document is to highlight major changes in the VSS specification (syntax and/or signals). +The intent of this document is to highlight major changes in the VSS specification (syntax and/or signals). It shall include all changes that affect backward compatibility or may be important to know when upgrading from one version to another. It typically does not list all changes to signals. It includes changes that are included in released version, but also changes planned for upcoming releases. *This document only contains changes introduced in VSS 3.0 or later!* - - ## VSS 3.0 [Complete release notes](https://github.com/COVESA/vehicle_signal_specification/releases/tag/v3.0) @@ -16,9 +14,9 @@ It includes changes that are included in released version, but also changes plan ### Instantiate A new attribute `instantiate` has been added to the syntax to exclude a child-node from the instantiation of the *direct* parent node. -This attribute is by default true and is only relevant to use for signals +This attribute is by default true and is only relevant to use for signals. -An example on how this signals shall be handled by tools: +An example on how these signals shall be handled by tools: ```YAML Vehicle.X: @@ -78,8 +76,7 @@ From VSS 3.0 this attribute has been renamed to `allowed`. The background is tha as it does not correspond to enum definitions in many programming languages, but rather just is a limitation of what values that are supported by the signal. - -All signals in VSS previously using `enum`has been updated to use `allowed`, like in the example below: +All signals in VSS previously using `enum` have been updated to use `allowed`, like in the example below: ``` LowVoltageSystemState: @@ -112,13 +109,13 @@ The background is that the old representation included limitations and ambiguiti ### Struct Support (Experimental) VSS has been extended with syntax to define structs, and to use them for signals. -For VSS 3.1 support is only experimental and syntax may change. +For VSS 3.1, support is only experimental and syntax may change. *Note: Only a subset of VSS-tools for VSS 3.1 supports structs!* ### Actuator and Sensor Attributes -VSS has two attributes `sensor` and `actuator` that gives the possibility to specify which system/entity that provides the value +VSS has two attributes `sensor` and `actuator` that gives the possibility to specify which system/entity provides the value or tries to actuate the value. A possible hypothetical example is shown below showing that it is `TemperatureSensorUnderDriverSeat` that provides the values of `Vehicle.Cabin.Temperature` and it is `HVACSystem` that tries to assure that the specified temperature is achieved. These two attributes have never been used by signals in the VSS repository and it has been decided that these attributes no longer shall @@ -135,7 +132,7 @@ Vehicle.Cabin.Temperature: ``` For VSS 3.1 the two attributes will remain in the VSS Syntax, but are marked as deprecated. -No change to tooling is implemented, as the vss-tools already today give a warning if the attributes are used: +No change to tooling is implemented, as the vss-tools already give a warning if the attributes are used: ``` Warning: Attribute(s) sensor in element Temperature not a core or known extended attribute. @@ -175,45 +172,70 @@ have been removed from the [VSS syntax](docs-gen/content/rule_set/data_entry/sen * `Vehicle.Powertrain.FuelSystem.TimeSinceStart` -## VSS 4.1 (Latest Release) +## VSS 4.1 ### Unit file syntax updated, Quantity file introduced A new syntax for unit files is introduced. Old syntax still supported. It is also possible to define quantity files, and a default quantity file (`quantities.yaml`) -has been added +has been added. ### New signals -Some signal have been added. +Some signals have been added. ### Updated tool dependency -A new version of vss-tools is used, with support for static IDs and jsconschema. +A new version of vss-tools is used, with support for static IDs and jsonschema. ### Deprecated or Deleted signals * `Vehicle.Cabin.Seat.*.*.Heating` deprecated from 4.1. New signal `Vehicle.Cabin.Seat.*.*.HeatingCooling` added. +## VSS 4.2 (Latest Release) + +### New signals + +New signals in the following areas + +* Engine Coolant and Engine Oil +* Wheel Angular Speed +* Screen Mirroring +* Head Position and Eye Gaze +* TimeInUse for electrical motors +* Battery Precondition + ## Planned Changes VSS 5.0 +### UUID removed from release artifacts + +VSS Release artifacts (VSS standard catalog in various formats) will no longer contain UUID information. +If you need artifacts with UUID you need to generate the artifact yourself. + +Instructions: + +1. Clone the repo and check out the tag you want, for example `git checkout v5.0`. +2. Update submodules, for example `git submodule update --init`. +3. Add `--uuid` as argument to the relevant command in `Makefile`. +4. Run generation, for example `make csv`. + ### OBD Branch deprecated The `Vehicle.OBD` branch is now deprecated. The plan is to remove it in VSS 6.0. The background is a decision that VSS standard catalog shall not contain a one-to-one representation of the OBD standard. Instead, VSS standard catalog may contain corresponding information elsewhere. As an example, instead of `Vehicle.OBD.EngineSpeed` (PID `0C`), the VSS signal `Vehicle.Powertrain.CombustionEngine.Speed` can be used. -Note that not all signals in `Vehicle.OBD` has "duplicates", especially in the area of combustion engine control +Note that not all signals in `Vehicle.OBD` have "duplicates", especially in the area of combustion engine control (like Oxygen sensor lambda and voltage readings) VSS currently does not have any counterparts in other parts of the tree. -What to do if you as of today use signals from the OBD file +What to do if you as of today use signals from the OBD file: -* Check if any suitable replacement signal exist - Example: if you use `Vehicle.OBD.Speed`, consider using `Vehicle.Speed` instead +* Check if any suitable replacement signal exist. + Example: if you use `Vehicle.OBD.Speed`, consider using `Vehicle.Speed` instead. * If not and the data may be of general interest; consider creating a pull request with a replacement signal. - Example: VSS as of today only have Lambda information in OBD branch + Example: VSS as of today only have Lambda information in OBD branch. If you need VSS signals for Lambda, consider creating new signals in `Vehicle.Powertrain.CombustionEngine` branch. * If you really need the signals in this file and cannot replace them, then consider using the overlay file in the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 061f1a30..88612bb5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Introduction to VSS Contribution Process -The COVESA VSS project has public two GitHub repositories +The COVESA VSS project has two public GitHub repositories: - [Vehicle Signal Specification (VSS)](https://github.com/COVESA/vehicle_signal_specification), containing signal specifications and documentation. - [VSS Tools](https://github.com/COVESA/vss-tools), containing tools for validating and transforming VSS specifications. @@ -15,13 +15,13 @@ There are two main methods to propose changes or extensions to VSS: All contributions must follow the [COVESA contribution guidelines](https://www.covesa.global/contribute). -The VSS project has regular meetings at Tuesdays 16.00 CET (see [COVESA VSS Wiki](https://wiki.covesa.global/display/WIK4/VSS+-+Vehicle+Signal+Specification)). -In the meetings Pull Requests and Issues are discussed, and if a Pull Request is acceptable the meeting will decide that it shall be merged. +The VSS project has regular meetings on Tuesdays at 16.00 CET and CEST in the summer (see [COVESA VSS Wiki](https://wiki.covesa.global/display/WIK4/VSS+-+Vehicle+Signal+Specification)). +In the meetings Pull Requests (PRs) and Issues are discussed and, if a Pull Request is accepted, a decision to merge the PR will be made. Everyone interested is welcome to join the meetings. ## Creating a Pull Request towards VSS -This is the typical workflow for preparing a pull request. A Github account is required. +This is the typical workflow for preparing a pull request. A GitHub account is required. 1. Create a personal or company fork of the [VSS repository](https://github.com/COVESA/vehicle_signal_specification) and/or [VSS-Tools repository](https://github.com/COVESA/vss-tools). @@ -31,9 +31,9 @@ This is the typical workflow for preparing a pull request. A Github account is r 5. Introduce the wanted changes or extensions in your local development environment, see guidelines below. If you want change/extend VSS-signals, it is the *.vspec files in the [spec](https://github.com/COVESA/vehicle_signal_specification/tree/master/spec) folder that needs to be updated. -6. Verify that your changes fulfil VSS Continuous Integration requirements, see [BUILD.md](BUILD.md) for some guidance. +6. Verify that your changes fulfill VSS Continuous Integration requirements, see [BUILD.md](BUILD.md) for some guidance. 7. Create a commit and upload to your own fork. -8. In the GitHub UI create a Pull Request from your fork to the master branch of [the VSS repository](https://github.com/COVESA/vehicle_signal_specification). +8. In the GitHub UI, create a Pull Request from your fork to the master branch of [the VSS repository](https://github.com/COVESA/vehicle_signal_specification). 9. Validate that automatic build checks for the PR succeed. ## Handling of the created Pull Request @@ -43,9 +43,9 @@ This is the typical workflow for preparing a pull request. A Github account is r It is preferable if the PR creator can participate and give a quick introduction on the rationale for the change. 3. Unless trivial, PRs shall typically be open for at least a week before merging is considered, to give time for comments. 4. If needed, the PR creator needs to refactor the PR to address received comments and remarks. -4. After a while, if all comments and concerns have been sorted out and no-one objects merging the PR the meeting will decide to merge the PR. +4. After a while, if all comments and concerns have been sorted out and no-one objects merging, a decision will be made in the meeting to merge the PR. It is not guaranteed that all PRs will be accepted. The VSS meeting may reject and close Pull Requests. -5. A VSS maintainer will perform the merge. +5. A VSS maintainer will perform the final merge. ## Guidelines and Recommendations @@ -55,7 +55,7 @@ This section includes general guidelines and recommendations for anyone interest COVESA has defined [contribution guidelines](https://www.covesa.global/contribute). -Every contribution must carry the following sign-off line with your real name and email address: +Every contribution (commit) must carry the following sign-off line with your real name and email address: `Signed-off-by: Firstname Lastname ` @@ -69,7 +69,7 @@ This currently applies to the following file types: * VSS source files (`*.vspec`) * Python files (vss-tools, `*.py`) -Those files shall have copyright statement of this form, inspired by the [Eclipse generic copyright header](https://www.eclipse.org/projects/handbook/#ip-copyright-headers). +Those files shall have copyright statement of the following form, inspired by the [Eclipse generic copyright header](https://www.eclipse.org/projects/handbook/#ip-copyright-headers). Copyright/License-statement may also be added to other files if considered relevant. ``` @@ -82,12 +82,12 @@ Copyright/License-statement may also be added to other files if considered relev # SPDX-License-Identifier: MPL-2.0 ``` -Where XXXX is the year the file was originally created, no need to update or append new years or a range of years later. +Where {year} is the year the file was originally created. No need to update or append new years or a range of years later. ### VSS Signals shall be generic -Signals added to standard VSS shall be generic, i.e. it shall be possible that other manufacturers can reuse the signal. -Manufacturer-specific signals shall preferably be part of private overlays, and not part of standard VSS. +Signals added to standard VSS shall be generic, i.e. it shall be possible for other manufacturers to reuse the signal. +Manufacturer-specific signals shall preferably be part of private overlays and not part of standard VSS. ### Logical path @@ -106,7 +106,7 @@ It shall be possible to interpret a signal value by reading the signal descripti Describe if needed how the value shall be calculated/interpreted, for example if it is based on a standard or if it is up to the manufacturer to select algorithm/method. -* Example: A signal Vehicle.Weight would be ambiguous unless you specify that it refers to e.g. gross weight or curb weight. +* Example: A signal Vehicle.Weight would be ambiguous unless you specify that it refers to gross weight or curb weight. * Example: Specifying an allowed value `MODE_2` is ambiguous unless you also specify what `MODE_2` means, e.g. by referring to a standard. ### No duplicates @@ -117,19 +117,19 @@ VSS generally avoids to have duplicates in the signal tree, i.e. signals with sa Try to reuse the same style as used for existing signals. Only specify min/max-values if there is a logical reason to limit the range. -Boolean signals should start with `Is*`. +Boolean signals should start with `Is`, as in `IsOpen`. American English is preferred over British English. No trailing blanks. Follow the style guide in the [documentation](https://covesa.github.io/vehicle_signal_specification/rule_set/basics/#style-guide). ### No scaling, SI-unit, natural datatype -VSS is not concerned with how signals are transmitted, and does not consider scaling/offset typically used in transport protocols. +VSS is not concerned with how signals are transmitted and does not consider scaling/offset typically used in transport protocols. VSS signals typically use the unit used by humans when talking about the value, but prefers SI-units when feasible, see [documentation](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_unit_types/) for all supported units. If it is unlikely that someone is interested in decimals for this value, select a signed or unsigned integer type. Select a size which with reasonable margins can cover all vehicles. -If it is likely that decimal values are needed select float or if relevant double. +If it is likely that decimal values are needed, select float or, if relevant, double. ### Avoid backward incompatible changes @@ -138,6 +138,6 @@ Merging can be delayed, as VSS may decide to wait with the change until the next ### Getting Support -To avoid time consuming refactoring it could for bigger contributions be relevant to ask VSS if the wanted changes +To avoid time consuming refactoring it could, for bigger contributions, be relevant to ask VSS if the wanted changes seems to be reasonable and likely will be accepted by VSS. Create an [issue](https://github.com/COVESA/vehicle_signal_specification/issues) and describe what you intend to do and ask for feedback. You can also create a draft pull request at an early stage and ask for comments. diff --git a/README.md b/README.md index 7ec5d15b..9857bf40 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ # VEHICLE SIGNAL SPECIFICATION - [![License](https://img.shields.io/badge/License-MPL%202.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) [![Build Status](https://github.com/COVESA/vehicle_signal_specification/actions/workflows/buildcheck.yml/badge.svg)](https://github.com/COVESA/vehicle_signal_specification/actions/workflows/buildcheck.yml?query=branch%3Amaster) The overall goal of the Vehicle Signal Specification (VSS) is to create a common understanding of vehicle signals in order to reach a “common language” independent of the protocol or serialisation format. -Please find the official documentation at: [Vehicle Signal Specification](https://covesa.github.io/vehicle_signal_specification/) +Please find the official documentation at: [Vehicle Signal Specification](https://covesa.github.io/vehicle_signal_specification/). ## Getting started @@ -38,7 +37,7 @@ resulting in artifact names of the form `vss_rel_.` where for released versions and `X.Y-dev` for ongoing work in master-branch towards version `X.Y`. Version is also visible in the [Vehicle.vspec](spec/Vehicle/Vehicle.vspec) file where `VersionVSS.Label` typically is -`dev` for ongoing work in master-branch and an empty string for released versions. +`-dev` for ongoing work in master-branch and an empty string for released versions. Versions are tagged in the form `vX.Y(.Z)` and the same syntax is used as names for VSS releases. VSS-tools is tagged but not released. diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 61fe8152..2dce7009 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -1,4 +1,4 @@ -**(C) 2016 Jaguar Land Rover**
+**Copyright (c) 2016 Contributors to COVESA**
All files and artifacts in this repository are licensed under the provisions of the license provided by the LICENSE file in this repository. @@ -19,12 +19,12 @@ contributors. Pull requests [PR] are **always** initiated from a **fork** and not through a feature branch in the main repository. PRs are reviewed, discussed and merged -through the public github repository. +through the public GitHub repository. A PR is merged earliest after one week to give a fair chance of reviewing. Each release is incrementally numbered, starting with 1. -A release is tagged in git with the tag +A release is tagged in git with the tag: v[m.n]