docs(vehicle_info): add docs for versioning (autowarefoundation#6069)

Signed-off-by: kosuke55 <[email protected]> remove non-support Signed-off-by: kosuke55 <[email protected]> fix link Signed-off-by: kosuke55 <[email protected]> add yaml Signed-off-by: kosuke55 <[email protected]> please check readme
Interplai · May 28, 2024 · 0da5936 · 0da5936
1 parent 2d0abd1
commit 0da5936
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 0 deletions.
diff --git a/vehicle/vehicle_info_util/Readme.md b/vehicle/vehicle_info_util/Readme.md
@@ -7,6 +7,35 @@ This package is to get vehicle info parameters.
 ### Description
 
 In [here](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/components/vehicle-dimensions/), you can check the vehicle dimensions with more detail.
+The current format supports only the Ackermann model. This file defines the model assumed in autoware path planning, control, etc. and does not represent the exact physical model. If a model other than the Ackermann model is used, it is assumed that a vehicle interface will be designed to change the control output for the model.
+
+### Versioning Policy
+
+We have implemented a versioning system for the `vehicle_info.param.yaml` file to ensure clarity and consistency in file format across different versions of Autoware and its external applications. Please see [discussion](https://github.com/orgs/autowarefoundation/discussions/4050) for the details.
+
+#### How to Operate
+
+- The current file format is set as an unversioned base version (`version:` field is commented out).
+- For the next update involving changes (such as additions, deletions, or modifications):
+  - Uncomment and update the version line at the beginning of the file.
+  - Initiate versioning by assigning a version number, starting from `0.1.0`. Follow the semantic versioning format (MAJOR.MINOR.PATCH).
+  - Update this Readme.md too.
+- For subsequent updates, continue incrementing the version number in accordance with the changes made.
+  - Discuss how to increment version depending on the amount of changes made to the file.
+
+```yaml
+/**:
+  ros__parameters:
+    # version: 0.1.0 # Uncomment and update this line for future format changes.
+    wheel_radius: 0.383
+    ...
+```
+
+#### Why Versioning?
+
+- Consistency Across Updates: Implementing version control will allow accurate tracking of changes over time and changes in vehicle information parameters.
+- Clarity for External Applications: External applications that depend on `vehicle_info.param.yaml` need to reference the correct file version for optimal compatibility and functionality.
+- Simplified Management for Customized Branches: Assigning versions directly to the `vehicle_info.param.yaml` file simplifies management compared to maintaining separate versions for multiple customized Autoware branches. This approach streamlines version tracking and reduces complexity.
 
 ### Scripts
 

diff --git a/vehicle/vehicle_info_util/config/vehicle_info.param.yaml b/vehicle/vehicle_info_util/config/vehicle_info.param.yaml
@@ -1,5 +1,6 @@
 /**:
   ros__parameters:
+    # version: 0.1.0 # uncomment this line in the next update of this file format. please check Readme.md
     wheel_radius: 0.39
     wheel_width: 0.42
     wheel_base: 2.74 # between front wheel center and rear wheel center