Adopt Netplan man-pages & examples to a consistent YAML style (flow vs block)

Bug #1999669 reported by XSpielinbox
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Netplan
Triaged
Wishlist
Unassigned
netplan.io (Ubuntu)
Invalid
Undecided
Unassigned

Bug Description

Neither the man page of Netplan in Ubuntu nor the documentation on https://netplan.io states what Version of YAML Netplan is using or what style guidelines one should adhere too.

The link on the website behind "YAML" links to the YAML 1.1 Spec, but there is no other way to notice this is the used version. I would expect that when a specific Version isn't stated, the latest version is used, which is not the case. I would therefore suggest, Netplan switches to YAML version 1.2.2.
Independent of that, I believe, the YAML version should be stated explicitly in the documentation.

Especially for the booleans this becomes an issue. 'yes' and 'no' are only valid booleans in YAML 1.1, but not YAML 1.2.x. Especially with the irritating mix of 'yes'/'no' and 'true'/'false' in the documentation and the examples - sometimes even within one configuration or for one option - this is very confusing.
I would strongly suggest that Netplan switches to using 'true'/'false' exclusively and at least issues some statement about style on that. This would be also useful for any potential future upgrade in the used YAML version.

Also Netplan documentation, man pages and examples use a confusing mix of flow style and block style. Though I would suggest to choose and use only a single style for the whole config for simplicity and clarity reasons, it would be at least good to not use different styles for the exact same option without any explanation or mention that these too functionally equivalent styles exist in YAML and both supported in Netplan.

summary: - unclear YAML sytle and version
+ unclear YAML style and version
Lukas Märdian (slyon)
tags: added: docs
Changed in netplan:
importance: Undecided → Medium
status: New → Triaged
Lukas Märdian (slyon)
Changed in netplan.io (Ubuntu):
status: New → Triaged
Revision history for this message
Lukas Märdian (slyon) wrote : Re: unclear YAML style and version

Netplan is using libyaml in the background to handle the YAML data, which only supports YAML v1.1 at this time. Furthermore, Netplan needs to stay backwards compatible with the "yes/"no" booleans and we cannot easily break the existing schema.

I've updated our documentation to mention this:
https://netplan.readthedocs.io/en/latest/reference.html
https://github.com/canonical/netplan/commit/db043801d0d7838d84cb7d0e4e07b6088e2d5771

And I will update this bug report to be a feature request for YAML v1.2 spec support.

Changed in netplan:
importance: Medium → Low
Changed in netplan.io (Ubuntu):
status: Triaged → Invalid
summary: - unclear YAML style and version
+ Upgrade to Netplan schema to YAML 1.2.x spec
Changed in netplan:
importance: Low → Wishlist
summary: - Upgrade to Netplan schema to YAML 1.2.x spec
+ Upgrade Netplan schema to YAML 1.2.x spec
Revision history for this message
XSpielinbox (xspielinbox) wrote (last edit ): Re: Upgrade Netplan schema to YAML 1.2.x spec

Thank you.

However, the upgrade of the YAML version was just a suggestion.
I can understand, that for backwards compatibility does not plan to upgrade the YAML version without good preparation, especially if migrating to a different YAML library would be needed. I see that this does not make sense at the moment.
But especially considering this, I find it way more important to clarify what the YAML style should be (within the current version) that Netplan config should adhere too and make it consistent. After all, this would be a prerequisite to some day upgrade the YAML version. Changing this issue to a "feature request" for that does not make sense to me as long as this is not resolved.

And as stated above, I see the importance of such a "code style" not only in preparation, but especially in making it easier and less confusing to work with Netplan, especially for newcomers.
This was the main reasoning behind my issue. Sorry, if this wasn't clear.

Lukas Märdian (slyon)
summary: - Upgrade Netplan schema to YAML 1.2.x spec
+ Adopt Netplan man-pages & examples to a consistend YAML style (flow vs
+ block)
summary: - Adopt Netplan man-pages & examples to a consistend YAML style (flow vs
+ Adopt Netplan man-pages & examples to a consistent YAML style (flow vs
block)
Lukas Märdian (slyon)
tags: added: documentation
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.