[Bug 1999669] [NEW] unclear YAML sytle and version

[XSpielinbox]

Public bug reported:

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.

** Affects: netplan
     Importance: Undecided
         Status: New

** Affects: netplan.io (Ubuntu)
     Importance: Undecided
         Status: New

** Also affects: netplan.io (Ubuntu)
   Importance: Undecided
       Status: New

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to netplan.io in Ubuntu.
Matching subscriptions: foundations-bugs
https://bugs.launchpad.net/bugs/1999669

Title:
  unclear YAML sytle and version

Status in netplan:
  New
Status in netplan.io package in Ubuntu:
  New

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.

To manage notifications about this bug go to:
https://bugs.launchpad.net/netplan/+bug/1999669/+subscriptions