You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+18-18Lines changed: 18 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Introduction to VSS Contribution Process
2
2
3
-
The COVESA VSS project has public two GitHub repositories
3
+
The COVESA VSS project has two public GitHub repositories:
4
4
5
5
-[Vehicle Signal Specification (VSS)](https://github.com/COVESA/vehicle_signal_specification), containing signal specifications and documentation.
6
6
-[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:
15
15
16
16
All contributions must follow the [COVESA contribution guidelines](https://www.covesa.global/contribute).
17
17
18
-
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)).
19
-
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.
18
+
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)).
19
+
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.
20
20
Everyone interested is welcome to join the meetings.
21
21
22
22
## Creating a Pull Request towards VSS
23
23
24
-
This is the typical workflow for preparing a pull request. A Github account is required.
24
+
This is the typical workflow for preparing a pull request. A GitHub account is required.
25
25
26
26
1. Create a personal or company fork of the [VSS repository](https://github.com/COVESA/vehicle_signal_specification)
@@ -31,9 +31,9 @@ This is the typical workflow for preparing a pull request. A Github account is r
31
31
5. Introduce the wanted changes or extensions in your local development environment, see guidelines below.
32
32
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
33
33
needs to be updated.
34
-
6. Verify that your changes fulfil VSS Continuous Integration requirements, see [BUILD.md](BUILD.md) for some guidance.
34
+
6. Verify that your changes fulfill VSS Continuous Integration requirements, see [BUILD.md](BUILD.md) for some guidance.
35
35
7. Create a commit and upload to your own fork.
36
-
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).
36
+
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).
37
37
9. Validate that automatic build checks for the PR succeed.
38
38
39
39
## 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
43
43
It is preferable if the PR creator can participate and give a quick introduction on the rationale for the change.
44
44
3. Unless trivial, PRs shall typically be open for at least a week before merging is considered, to give time for comments.
45
45
4. If needed, the PR creator needs to refactor the PR to address received comments and remarks.
46
-
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.
46
+
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.
47
47
It is not guaranteed that all PRs will be accepted. The VSS meeting may reject and close Pull Requests.
48
-
5. A VSS maintainer will perform the merge.
48
+
5. A VSS maintainer will perform the final merge.
49
49
50
50
## Guidelines and Recommendations
51
51
@@ -55,7 +55,7 @@ This section includes general guidelines and recommendations for anyone interest
55
55
56
56
COVESA has defined [contribution guidelines](https://www.covesa.global/contribute).
57
57
58
-
Every contribution must carry the following sign-off line with your real name and email address:
58
+
Every contribution (commit) must carry the following sign-off line with your real name and email address:
@@ -69,7 +69,7 @@ This currently applies to the following file types:
69
69
* VSS source files (`*.vspec`)
70
70
* Python files (vss-tools, `*.py`)
71
71
72
-
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).
72
+
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).
73
73
Copyright/License-statement may also be added to other files if considered relevant.
74
74
75
75
```
@@ -82,12 +82,12 @@ Copyright/License-statement may also be added to other files if considered relev
82
82
# SPDX-License-Identifier: MPL-2.0
83
83
84
84
```
85
-
Where XXXX is the year the file was originally created, no need to update or append new years or a range of years later.
85
+
Where {year} is the year the file was originally created. No need to update or append new years or a range of years later.
86
86
87
87
### VSS Signals shall be generic
88
88
89
-
Signals added to standard VSS shall be generic, i.e. it shall be possible that other manufacturers can reuse the signal.
90
-
Manufacturer-specific signals shall preferably be part of private overlays, and not part of standard VSS.
89
+
Signals added to standard VSS shall be generic, i.e. it shall be possible for other manufacturers to reuse the signal.
90
+
Manufacturer-specific signals shall preferably be part of private overlays and not part of standard VSS.
91
91
92
92
### Logical path
93
93
@@ -106,7 +106,7 @@ It shall be possible to interpret a signal value by reading the signal descripti
106
106
Describe if needed how the value shall be calculated/interpreted,
107
107
for example if it is based on a standard or if it is up to the manufacturer to select algorithm/method.
108
108
109
-
* Example: A signal Vehicle.Weight would be ambiguous unless you specify that it refers to e.g. gross weight or curb weight.
109
+
* Example: A signal Vehicle.Weight would be ambiguous unless you specify that it refers to gross weight or curb weight.
110
110
* Example: Specifying an allowed value `MODE_2` is ambiguous unless you also specify what `MODE_2` means, e.g. by referring to a standard.
111
111
112
112
### No duplicates
@@ -117,19 +117,19 @@ VSS generally avoids to have duplicates in the signal tree, i.e. signals with sa
117
117
118
118
Try to reuse the same style as used for existing signals.
119
119
Only specify min/max-values if there is a logical reason to limit the range.
120
-
Boolean signals should start with `Is*`.
120
+
Boolean signals should start with `Is`, as in `IsOpen`.
121
121
American English is preferred over British English.
122
122
No trailing blanks.
123
123
Follow the style guide in the [documentation](https://covesa.github.io/vehicle_signal_specification/rule_set/basics/#style-guide).
124
124
125
125
### No scaling, SI-unit, natural datatype
126
126
127
-
VSS is not concerned with how signals are transmitted, and does not consider scaling/offset typically used in transport protocols.
127
+
VSS is not concerned with how signals are transmitted and does not consider scaling/offset typically used in transport protocols.
128
128
VSS signals typically use the unit used by humans when talking about the value, but prefers SI-units when feasible,
129
129
see [documentation](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_unit_types/) for all supported units.
130
130
If it is unlikely that someone is interested in decimals for this value, select a signed or unsigned integer type.
131
131
Select a size which with reasonable margins can cover all vehicles.
132
-
If it is likely that decimal values are needed select float or if relevant double.
132
+
If it is likely that decimal values are needed, select float or, if relevant, double.
133
133
134
134
### Avoid backward incompatible changes
135
135
@@ -138,6 +138,6 @@ Merging can be delayed, as VSS may decide to wait with the change until the next
138
138
139
139
### Getting Support
140
140
141
-
To avoid time consuming refactoring it could for bigger contributions be relevant to ask VSS if the wanted changes
141
+
To avoid time consuming refactoring it could, for bigger contributions, be relevant to ask VSS if the wanted changes
142
142
seems to be reasonable and likely will be accepted by VSS. Create an [issue](https://github.com/COVESA/vehicle_signal_specification/issues)
143
143
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.
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.
8
7
9
-
Please find the official documentation at: [Vehicle Signal Specification](https://covesa.github.io/vehicle_signal_specification/)
8
+
Please find the official documentation at: [Vehicle Signal Specification](https://covesa.github.io/vehicle_signal_specification/).
10
9
11
10
## Getting started
12
11
@@ -38,7 +37,7 @@ resulting in artifact names of the form `vss_rel_<version>.<type-suffix>` where
38
37
for released versions and `X.Y-dev` for ongoing work in master-branch towards version `X.Y`.
39
38
40
39
Version is also visible in the [Vehicle.vspec](spec/Vehicle/Vehicle.vspec) file where `VersionVSS.Label` typically is
41
-
`dev` for ongoing work in master-branch and an empty string for released versions.
40
+
`-dev` for ongoing work in master-branch and an empty string for released versions.
42
41
43
42
Versions are tagged in the form `vX.Y(.Z)` and the same syntax is used as names for VSS releases.
0 commit comments