Extend governance and changelog information

Signed-off-by: Erik Jaegervall <erik.jaegervall@se.bosch.com>

CHANGELOG.md

@@ -0,0 +1,145 @@
+# VSS Changelog
+
+The intention 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 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 (Latest Release)
+
+[Complete release notes](https://github.com/COVESA/vehicle_signal_specification/releases/tag/v3.0)
+
+### 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
+
+An example on how this signals shall be handled by tools:
+
+```YAML
+Vehicle.X:
+  type: branch
+  instances: Test[1,2]
+  description: High-level vehicle data.
+
+Vehicle.X.InstantiatedSignal:
+  type: attribute
+  description: "Instantiated Signal"
+  datatype: string
+
+Vehicle.X.NotInstantiatedSignal:
+  type: attribute
+  description: "Not Instantiated Signal"
+  datatype: string
+  instantiate: False
+```
+
+Results in the following dot-notated output:
+
+```
+Vehicle.X
+Vehicle.X.NotInstantiatedSignal
+Vehicle.X.Test1.NotInstantiatedSignal
+Vehicle.X.Test2.NotInstantiatedSignal
+```
+The new attribute is not used for any signals in VSS 3.0.
+For more information see [documentation](https://github.com/COVESA/vehicle_signal_specification/blob/master/docs-gen/content/rule_set/instances.md).
+
+### Changed Path to Battery Signals
+
+The path `Vehicle.Powertrain.Battery` was renamed to `Vehicle.Powertrain.TractionBattery`.
+The path name was changed to make it clear that the signals in the path concerns the traction battery (high voltage battery) used by electrical or hybrid vehicles,
+and not the supply battery (low voltage battery, typically 12 or 24 Volts).
+
+### Enum/Allowed attribute
+
+Before VSS 3.0 the attribute `enum` could be used to list allowed values for a VSS signals, like in the example below:
+
+```
+LowVoltageSystemState:
+  datatype: string
+  type: sensor
+  enum: [
+    "UNDEFINED", # State of low voltage system not known
+    "LOCK",      # Low voltage system off, steering lock or equivalent engaged
+    "OFF",       # Low voltage system off, steering lock or equivalent not engaged
+    "ACC",       # Vehicle Accessories on/living
+    "ON",        # Engine start enabled (e.g. ignition on, diesel pre-heating, electrical drive released)
+    "START"      # Engine starter relay closed (not applicable for electrical vehicles)
+    ]
+  description: State of the supply voltage of the control units (usually 12V).
+```
+
+From VSS 3.0 this attribute has been renamed to `allowed`. The background is that the old name was misleading,
+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:
+
+```
+LowVoltageSystemState:
+  datatype: string
+  type: sensor
+  allowed: [
+    'UNDEFINED', # State of low voltage system not known
+    'LOCK',      # Low voltage system off, steering lock or equivalent engaged
+    'OFF',       # Low voltage system off, steering lock or equivalent not engaged
+    'ACC',       # Vehicle Accessories on/living
+    'ON',        # Engine start enabled (e.g. ignition on, diesel pre-heating, electrical drive released)
+    'START'      # Engine starter relay closed (not applicable for electrical vehicles)
+    ]
+  description: State of the supply voltage of the control units (usually 12V).
+```
+
+If the old keyword `enum` is used most tools will ignore it and give a warning.
+
+```
+Warning: Attribute(s) enum in element Position not a core or known extended attribute.
+```
+
+### Seat signals
+
+The signals in `Vehicle.Cabin.Seat` have been significantly refactored.
+The background is that the old representation included limitations and ambiguities.
+
+## Planned Changes VSS 3.1 
+
+### Actuator and Sensor Attributes
+
+VSS has two attributes `sensor` and `actuator` that gives the possibility to specify which system/entity that 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
+be part of the official VSS syntax. If needed, this type of information shall be provided by overlays.
+
+```
+Vehicle.Cabin.Temperature:
+  type: actuator
+  description: Temperature in cabin
+  datatype: float
+  unit: km/h
+  sensor: 'TemperatureSensorUnderDriverSeat'
+  actuator: 'HVACSystem'
+```
+
+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:
+
+```
+Warning: Attribute(s) sensor in element Temperature not a core or known extended attribute.
+```
+
+## Planned Changes VSS 4.0
+
+### Actuator and Sensor Attributes
+
+The attributes `sensor` and `actuator`, deprecated from VSS 3.1, will be removed from the [VSS syntax](docs-gen/content/rule_set/data_entry/sensor_actuator.md).
+
+
+## Planned Changes VSS 5.0
+
+-

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Introduction to VSS Contribution Process
+
+The COVESA VSS project has public two 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.
+
+The examples below refer to the VSS repository, but the process is similar for the VSS-Tools repository.
+
+There are two main methods to propose changes or extensions to VSS:
+
+- If you have an idea or a question you can create an [issue](https://github.com/COVESA/vehicle_signal_specification/issues) in GitHub.
+- If you already have prepared changes or extension that you think would be interesting for COVESA to include in VSS
+  then you can create a [Pull Request (PR)](https://github.com/COVESA/vehicle_signal_specification/pulls).
+
+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.
+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.
+
+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).
+2. Clone the forked repository into your local development environment.
+3. Create a local branch based on the VSS master branch to use for the proposed changes.
+4. 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.
+5. Run "make travis_targets" to verify that the changes are syntactically correct and does not introduce any side effects.
+   This will verify that tools and test-cases in vss-tools repository accepts the changes.
+6. Create a commit and upload to your own fork.
+7. 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. Validate that automatic build checks for the PR succeed.
+
+## Handling of the created Pull Request
+
+1. The PR creator shall follow up on any comments or questions received on the Pull Request.
+2. The PR will be discussed at one of the next VSS weekly meetings. 
+   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.
+   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.
+
+## Guidelines and Recommendations
+
+This section includes general guidelines and recommendations for anyone interested in contributing to VSS.
+
+### 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.
+
+### Logical path
+
+VSS aims to put all signals in a logical path based on physical topology of the vehicle. 
+As an example, signals related to wheels should typically reside under `Vehicle.Chassis.Axle`.
+When proposing a new signal, reuse an existing path if a relevant path exists.
+
+### Consider adding a new file if adding a large number of signals
+
+VSS has no strict rules that every branch must have its own file,
+but if a file becomes too big you can consider splitting it if feasible.
+
+### Signals shall have a clear definition without ambiguities
+
+It shall be possible to interpret a signal value by reading the signal description.
+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: 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
+
+VSS generally avoids to have duplicates in the signal tree, i.e. signals with same purpose and description in different part of the tree.
+
+### Use existing style
+
+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*`.
+American English is preferred over British English.
+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 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.
+
+### Avoid backward incompatible changes
+
+VSS sometimes change or remove existing signals, but only if there is a good reason.
+Merging can be delayed, as VSS may decide to wait with the change until the next major release is prepared.
+
+### Getting Support
+
+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.
+

docs-gen/content/_index.md

@@ -3,7 +3,7 @@ title: "Vehicle Signal Specification"
 ---
 # Vehicle Signal Specification
 
-The Vehicle Signal Specification (VSS) is an initiative by [COVESA](https://www.covesa.global/) to define a syntax and a catalogue for vehicle signals.
+The Vehicle Signal Specification (VSS) is an initiative by [COVESA](https://www.covesa.global/) to define a syntax and a catalog for vehicle signals.
 The source code and releases can be found in the [VSS github repository](https://github.com/COVESA/vehicle_signal_specification).
 Some tools for parsing and converting VSS files can be found in the [VSS-tools github repository](https://github.com/COVESA/vss-tools).
 
@@ -12,7 +12,8 @@ This documentation gives you an overview of VSS:
 * [Introduction](/vehicle_signal_specification/introduction) </br> Read this part if you want to know more
 about what the specification is all about, what's in and out and how to quickly
  browse through the current status.
+* [Governance](/vehicle_signal_specification/governance) </br> Introduction to VSS governance model and change log.
 * [Rule Set](/vehicle_signal_specification/rule_set) </br> Get familiar with the rule set behind the
-specification, the structure, the format and concepts. Basic knowledge needed
-to write first extensions.
+specification, the structure, the format and concepts.
+* [License](/vehicle_signal_specification/license) </br> Information on the VSS license.
 * [Ecosystem](/vehicle_signal_specification/ecosystem) How to use the specification? Check out the existing tools and standards to transform or make use of VSS.

docs-gen/content/governance/_index.md

@@ -0,0 +1,75 @@
+---
+title: Governance
+weight: 15
+chapter: false
+---
+
+# Governance
+
+The Vehicle Signal Specification (VSS) project is an initiative by [COVESA](https://www.covesa.global/) to define a syntax and a catalog for vehicle signals.
+
+The artifacts maintained by the VSS project consist of:
+
+* Source code, documentation and releases in the [VSS github repository](https://github.com/COVESA/vehicle_signal_specification).
+* Tools for parsing and converting VSS files in the [VSS-tools github repository](https://github.com/COVESA/vss-tools).
+
+The VSS project has an informal structure with a chair and github maintainers appointed by COVESA.
+Tasks for the chair includes hosting regular meeting to discuss incoming pull requests and issues, as well as roadmap and release planning.
+
+## Contribution process
+
+Anyone may propose changes to VSS. It is up to the VSS project to decide if the changes are feasible to include in VSS.
+The VSS project does not have any developers or maintainers paid by COVESA.
+Instead, the VSS project relies on voluntary contributions, typically from member organizations.
+The maintainers are expected to review incoming pull requests.
+All contributions must follow the [COVESA contribution guidelines](https://www.covesa.global/contribute).
+
+In general, pull requests shall be opened for at least a week before being merged to give time for COVESA members to review the pull request and provide comments.
+In case of larger changes or changes that affect backward compatibility pull requests are typically opened for a longer period, to allow for a through review.
+Pull requests, unless trivial, are typically merged first after a decision at one of the regular VSS meetings, see link at [COVESA VSS wiki page](https://wiki.covesa.global/display/WIK4/VSS+-+Vehicle+Signal+Specification).
+These rules concerns primarily normative content (see below), non-normative content may be updated without thorough reviews.
+
+For more information and guides on how to contribute see [CONTRIBUTING.md](https://github.com/COVESA/vehicle_signal_specification/blob/master/CONTRIBUTING.md).
+
+## Branches
+
+VSS development is typically developed in the master branch only.
+Each release is tagged and a maintenance branch is created (e.g. `release/3.0`) which could be used as target for pull requests intending to patch a release.
+
+## Normative vs. non-normative content
+
+The VSS repositories contain some artifacts that can be considered normative, i.e. an implementation claiming to "support" VSS shall:
+
+* Support signals defined according to the rules in the VSS documentation
+  ([source](https://github.com/COVESA/vehicle_signal_specification/tree/master/docs-gen), [generated](https://covesa.github.io/vehicle_signal_specification/))
+* Support the signals currently defined in VSS.
+    * The signals in source format (*.vspec files) can be found in [Github repository](https://github.com/COVESA/vehicle_signal_specification/tree/master/spec).
+    * Derived formats supported by VSS project are included in each [release](https://github.com/COVESA/vehicle_signal_specification/releases), 
+      originating from the tools in the VSS-tools github repository](https://github.com/COVESA/vss-tools).
+
+In addition to this the VSS repositores contain artifacts that currently are considered non-normative. This includes immature concepts and work-in progress. Non-normative content include:
+
+* [VSS Github Wiki](https://github.com/COVESA/vehicle_signal_specification/wiki)
+* [VSS Tools Wiki](https://github.com/COVESA/vss-tools/wiki)
+* [Overlays and Profiles](https://github.com/COVESA/vehicle_signal_specification/tree/master/overlays)
+* [Contributed tools](https://github.com/COVESA/vss-tools/tree/master/contrib)
+
+The list of what is considered normative and non-normative is no static, it may change over time.
+
+## Handling of backward compatibility
+
+The VSS project aims to keep backward compatibility as far as feasible.
+VSS is however an evolving syntax and catalog and there are still areas where changes are need to fit the need of users.
+Changes that breaks backward compatibility are typically introduced only in major releases (e.g. `X.0`) and shall be documented in release notes.
+This concerns changes to syntax and signals, but also to tools.
+
+The VSS project has introduced a [deprecation concept](../rule_set/basics.md#deprecation-since-version-21).
+If possible, when e.g. renaming or moving a signal or changing tools the old signal or parameter set shall be kept but marked as deprecated.
+That allows the change to be introduced in a minor version (e.g. `X.Y`). The old signal shall be removed first in the next major release, or later if needed.
+
+A history of past changes and planned changes that affects backward compatibility can be found in the [Changelog](https://github.com/COVESA/vehicle_signal_specification/blob/master/CHANGELOG.md).
+
+## Release Process
+
+The release process is further described in the [Github repository](https://github.com/COVESA/vehicle_signal_specification/blob/master/RELEASE_PROCESS.md).
+

docs-gen/content/introduction/_index.md

@@ -6,4 +6,4 @@ chapter: true
 
 # Introduction
 
-Discover what the Vehicle Signal  Specification is all about.
+Discover what the Vehicle Signal Specification is all about.