doc: change to hyphenated keys (#5909)

doc: change to hyphenated terms

Some words, and especially "metadata" are used in multiple
ways to describe multiple things. Convert to the following
standard.

user data -> user-data
vendor data -> vendor-data
meta data -> meta-data
instance data -> instance-data

Clarifications:

- "instance-data" describes data which is gathered from the
  IMDS: user-data, vendor-data, and meta-data.

- "metadata" may be used in the phrase "instance
  metadata service" (IMDS), to describe the service which 
  instance data is gathered from. Otherwise, avoid
  the word "metadata". It is too abstract to be generally useful
  in cloud-init documentation because it could be correctly used
  to describe almost any data.

Fixes GH-5555

cloudinit/config/schemas/schema-cloud-config-v1.json

@@ -444,7 +444,7 @@
         "ssh_redirect_user": {
           "type": "boolean",
           "default": false,
-          "description": "Boolean set to true to disable SSH logins for this user. When specified, all cloud meta-data public SSH keys will be set up in a disabled state for this username. Any SSH login as this username will timeout and prompt with a message to login instead as the **default_username** for this instance. Default: ``false``. This key can not be combined with **ssh_import_id** or **ssh_authorized_keys**."
+          "description": "Boolean set to true to disable SSH logins for this user. When specified, all cloud-provided public SSH keys will be set up in a disabled state for this username. Any SSH login as this username will timeout and prompt with a message to login instead as the **default_username** for this instance. Default: ``false``. This key can not be combined with **ssh_import_id** or **ssh_authorized_keys**."
         },
         "system": {
           "description": "Optional. Create user as system user with no home directory. Default: ``false``.",
@@ -662,7 +662,7 @@
           "type": "object",
           "deprecated": true,
           "deprecated_version": "24.2",
-          "deprecated_description": "System and/or distro specific settings. This is not intended to be overridden by user data or vendor data."
+          "deprecated_description": "System and/or distro specific settings. This is not intended to be overridden by user-data or vendor-data."
         }
       }
     },
@@ -2764,7 +2764,7 @@
           "additionalProperties": false,
           "properties": {
             "enabled": {
-              "description": "Whether vendor data is enabled or not. Default: ``true``.",
+              "description": "Whether vendor-data is enabled or not. Default: ``true``.",
               "oneOf": [
                 {
                   "type": "boolean",

cloudinit/util.py

@@ -1200,7 +1200,7 @@ def get_hostname_fqdn(cfg, cloud, metadata_only=False):
 
     @param cfg: Dictionary of merged user-data configuration (from init.cfg).
     @param cloud: Cloud instance from init.cloudify().
-    @param metadata_only: Boolean, set True to only query cloud meta-data,
+    @param metadata_only: Boolean, set True to only query meta-data,
         returning None if not present in meta-data.
     @return: a namedtuple of
         <hostname>, <fqdn>, <is_default> (str, str, bool).

doc/examples/cloud-config-add-apt-repos.txt

@@ -6,7 +6,7 @@
 # Additional apt configuration and repositories section.
 #
 #
-# Default: auto select based on cloud metadata
+# Default: auto select based on instance-data
 #  in ec2, the default is <region>.archive.ubuntu.com
 # apt:
 #   primary:
@@ -24,7 +24,7 @@
 #
 # if no mirror is provided by the DataSource, but 'search_dns' is
 # true, then search for dns names '<distro>-mirror' in each of
-# - fqdn of this host per cloud metadata
+# - fqdn of this host per meta-data
 # - localdomain
 # - no domain (which would search domains listed in /etc/resolv.conf)
 # If there is a dns entry for <distro>-mirror, then it is assumed that there

doc/examples/cloud-config-apt.txt

@@ -69,7 +69,7 @@ apt:
 
   # 1.3 primary/security archives
   #
-  # Default: none - instead it is auto select based on cloud metadata
+  # Default: none - instead it is auto select based on instance-data
   # so if neither "uri" nor "search", nor "search_dns" is set (the default)
   # then use the mirror provided by the DataSource found.
   # In EC2, that means using <region>.ec2.archive.ubuntu.com
@@ -96,7 +96,7 @@ apt:
         - http://us.archive.ubuntu.com/ubuntu
       # if no mirror is provided by uri or search but 'search_dns' is
       # true, then search for dns names '<distro>-mirror' in each of
-      # - fqdn of this host per cloud metadata
+      # - fqdn of this host per meta-data
       # - localdomain
       # - no domain (which would search domains listed in /etc/resolv.conf)
       # If there is a dns entry for <distro>-mirror, then it is assumed that

doc/man/cloud-init.1

@@ -9,8 +9,8 @@ cloud-init \- Cloud instance initialization
 .SH DESCRIPTION
 Cloud-init provides a mechanism for cloud instance initialization.
 This is done by identifying the cloud platform that is in use, reading
-provided cloud metadata and optional vendor and user
-data, and then initializing the instance as requested.
+cloud meta-data, vendor-data and user-data, and then initializing the
+instance as requested.
 
 .SH OPTIONS
 .TP

doc/module-docs/cc_disable_ec2_metadata/data.yaml

@@ -7,5 +7,5 @@ cc_disable_ec2_metadata:
   - comment: |
       Example 1:
     file: cc_disable_ec2_metadata/example1.yaml
-  name: Disable EC2 Metadata
-  title: Disable AWS EC2 Metadata
+  name: Disable EC2 Instance Metadata Service
+  title: Disable AWS EC2 Instance Metadata Service

doc/module-docs/cc_install_hotplug/data.yaml

@@ -1,7 +1,7 @@
 cc_install_hotplug:
   description: |
     This module will install the udev rules to enable hotplug if supported by
-    the datasource and enabled in the userdata. The udev rules will be
+    the datasource and enabled in the user-data. The udev rules will be
     installed as ``/etc/udev/rules.d/90-cloud-init-hook-hotplug.rules``.
 
     When hotplug is enabled, newly added network devices will be added to the

doc/module-docs/cc_update_etc_hosts/data.yaml

@@ -38,7 +38,7 @@ cc_update_etc_hosts:
 
       The strings ``$hostname`` and ``$fqdn`` are replaced in the template
       with the appropriate values, either from the config-config ``fqdn`` or
-      ``hostname`` if provided. When absent, the cloud metadata will be
+      ``hostname`` if provided. When absent, the meta-data will be
       checked for ``local-hostname`` which can be split into
       ``<hostname>.<fqdn>``.
 

doc/module-docs/cc_update_hostname/data.yaml

@@ -27,7 +27,7 @@ cc_update_hostname:
     file: cc_update_hostname/example4.yaml
   - comment: >
       Example 5: Set hostname to ``external`` instead of ``external.fqdn.me`` when
-      cloud metadata provides the ``local-hostname``: ``external.fqdn.me``.
+      meta-data provides the ``local-hostname``: ``external.fqdn.me``.
     file: cc_update_hostname/example5.yaml
   - comment: >
       Example 6: On a machine without an ``/etc/hostname`` file, don''t create

doc/rtd/development/contribute_docs.rst

@@ -43,7 +43,7 @@ web browser to open `index.html` to view and navigate the site.
 How are the docs structured?
 ============================
 
-We use `Diataxis`_ to organise our documentation. There is more detail on the
+We use `Diataxis`_ to organize our documentation. There is more detail on the
 layout of the ``doc`` directory in the :doc:`docs_layout` article.
 
 We also have a :doc:`style_docs` that will help you if you need to edit or

doc/rtd/development/datasource_creation.rst

@@ -82,8 +82,8 @@ and/or unused may be considered for eventual removal.
 Adding cloud-init support
 =========================
 
-There are multiple ways to provide `user data`, `metadata`, and
-`vendor data`, and each cloud solution prefers its own way. A datasource
+There are multiple ways to provide `user-data`, `meta-data`, and
+`vendor-data`, and each cloud solution prefers its own way. A datasource
 abstract base class defines a single interface to interact with the different
 clouds. Each cloud implementation must inherit from this base class to use this
 shared functionality and interface. See :file:`cloud-init/sources/__init__.py`

doc/rtd/development/docs_layout.rst

@@ -80,7 +80,7 @@ page.
 This subdirectory is of most interest to anyone who wants to create or update
 either the content of the documentation, or the styling of it.
 
-* The content of the documentation is organised according to the `Diataxis`_
+* The content of the documentation is organized according to the `Diataxis`_
   framework and can be found in the subdirectories: ``tutorial/``, ``howto/``,
   ``explanation/``, and ``reference/``.
 

doc/rtd/development/integration_tests.rst

@@ -17,7 +17,7 @@ Test definition
 ===============
 
 Tests are defined like any other ``pytest`` test. The ``user_data``
-mark can be used to supply the cloud-config user data. Platform-specific
+mark can be used to supply the cloud-config user-data. Platform-specific
 marks can be used to limit tests to particular platforms. The ``client``
 fixture can be used to interact with the launched test instance.
 

doc/rtd/development/internal_files.rst

@@ -20,8 +20,8 @@ subdirectories:
 
 The :file:`/var/lib/cloud/instance` directory is a symbolic link that points
 to the most recently used :file:`instance-id` directory. This folder contains
-the information ``cloud-init`` received from datasources, including vendor and
-user data. This can help to determine that the correct data was passed.
+the information ``cloud-init`` received from datasources, including vendor-data
+and user-data. This can help to determine that the correct data was passed.
 
 It also contains the :file:`datasource` file that contains the full information
 about which datasource was identified and used to set up the system.

doc/rtd/development/logging.rst

@@ -166,7 +166,7 @@ The default configuration is to emit events to the cloud-init log file
 at ``DEBUG`` level.
 
 Event reporting can be configured using the ``reporting`` key in cloud-config
-user data.
+user-data.
 
 Configuration
 -------------

doc/rtd/development/module_creation.rst

@@ -51,7 +51,7 @@ definition in `cloud-init-schema.json`_.
     - ``ONCE``: Runs only on first boot.
     - ``PER_INSTANCE``: Runs once per instance. When exactly this happens
       is dependent on the datasource, but may be triggered any time there
-      would be a significant change to the instance metadata. An example
+      would be a significant change to the instance-data. An example
       could be an instance being moved to a different subnet.
 
   - ``activate_by_schema_keys``: Optional list of cloud-config keys that will

doc/rtd/development/style_docs.rst

@@ -4,10 +4,8 @@ Documentation style guide
 Language
 --------
 
-Where possible, text should be written in UK English. However, discretion and
-common sense can both be applied. For example, where text refers to code
-elements that exist in US English, the spelling of these elements should not
-be changed to UK English.
+Where possible, text should be written in US English. However, discretion and
+common sense can both be applied.
 
 Try to be concise and to the point in your writing. It is acceptable to link
 to official documentation elsewhere rather than repeating content. It's also
@@ -87,6 +85,12 @@ It is generally best to avoid screenshots where possible. If you need to refer
 to text output, you can use code blocks. For diagrams, we recommend the use of
 `Mermaid`_.
 
+File names
+----------
+
+File names should be decorated with backticks to ensure monospace font is used
+to distinguish the name from regular text.
+
 Code blocks
 -----------
 
@@ -104,30 +108,30 @@ Vertical whitespace
 One newline between each section helps ensure readability of the documentation
 source code.
 
-Common words
-------------
-
-There are some common words that should follow specific usage in text:
-
-- **cloud-init**: Always hyphenated, and follows sentence case, so only
-  capitalised at the start of a sentence.
-- **metadata**, **datasource**: One word.
-- **user data**, **vendor data**: Two words, not to be combined or hyphenated.
-
-When referring to file names, which may be hyphenated, they should be decorated
-with backticks to ensure monospace font is used to distinguish them from
-regular text.
-
 Acronyms
 --------
 
-Acronyms are always capitalised (e.g., JSON, YAML, QEMU, LXD) in text.
+Acronyms are always capitalized (e.g., JSON, YAML, QEMU, LXD) in text.
 
 The first time an acronym is used on a page, it is best practice to introduce
 it by showing the expanded name followed by the acronym in parentheses. E.g.,
 Quick EMUlator (QEMU). If the acronym is very common, or you provide a link to
 a documentation page that provides such details, you will not need to do this.
 
+Common terms
+------------
+
+The following project terms should follow specific usage in text:
+
+- **cloud-init**: Always hyphenated, and follows sentence case, so only
+  capitalized at the start of a sentence.
+- **datasource**: One word.
+- **user-data**: Two words, always hyphenated.
+- **vendor-data**: Two words, always hyphenated.
+- **cloud-config**: Two words, always hyphenated.
+- **instance-data**: Two words, always hyphenated.
+- **meta-data**: Two words, always hyphenated.
+
 .. _Read the Docs: https://readthedocs.com/
 .. _Python style guide: https://devguide.python.org/documentation/markup/
 .. _Mermaid: https://mermaid.js.org/

doc/rtd/development/summit/2017_summit.rst

@@ -42,7 +42,7 @@ that they gave as a part of the summit:
   merge request CI process and encouraged this as a way for other OSes to
   participate.
 * **Using lxd for Rapid Development and Testing**: Scott demoed setting
-  userdata when launching a lxd instance and how this can be used in the
+  user-data when launching a lxd instance and how this can be used in the
   development process. He also discussed lxd image remotes and types of images.
 
 Breakout Sessions
@@ -52,7 +52,7 @@ In addition to the prepared demos, the summit had numerous sessions that were
 requested by the attendees as additional topics for discussion:
 
 * Netplan (v2 YAML) as primary format
-* How to query metadata
+* How to query instance-data
 * Version numbering
 * Device hot-plug
 * Python 3

doc/rtd/development/summit/2018_summit.rst

@@ -45,7 +45,7 @@ that they gave as a part of the summit:
   and there was a discussion on ending Python 2.7 support as well. An
   announcement to the mailing list is coming soon.
 * **Instance-data.json support and cloud-init cli**: Chad demoed a standard way
-  of querying instance data keys to enable scripting, templating, and access
+  of querying instance-data keys to enable scripting, templating, and access
   across all clouds.
 * **Multipass**: Alberto from the Canonical Multipass team joined us to demo
   the `Multipass`_ project. Multipass is the fastest way to get a virtual

doc/rtd/development/summit/2023_summit.rst

@@ -15,7 +15,7 @@ and to realign on the direction and goals of the project.
 The event was generously hosted by Microsoft this year at their Redmond campus
 in Seattle, Washington, and we are grateful to the Microsoft community members
 "on the ground" who coordinated with Canonical's cloud-init development team to
-help organise and run the event. Big thanks go as well to the Canonical
+help organize and run the event. Big thanks go as well to the Canonical
 community team for helping us to set up the event site, as well as for their
 support and guidance with all the planning involved.
 
@@ -29,7 +29,7 @@ our newer contributors in person.
 The first hybrid summit
 =======================
 
-This summit was organised as a hybrid event for the first time, and despite
+This summit was organized as a hybrid event for the first time, and despite
 some initial uncertainties about how to implement that, it worked very well.
 In-person attendees included developers and contributors from Microsoft,
 Google, Amazon, Oracle, openSUSE and we had remote presentations provided by
@@ -85,8 +85,8 @@ Presentation takeaways
   spelunking".
 
   This aligns well with Brett’s ongoing roadmap work to raise warnings from the
-  CLI and some of the strict JSON schema validation on network-config and user
-  data/vendor data.
+  CLI and some of the strict JSON schema validation on network-config and
+  user-data/vendor-data.
 
 * Good lessons from both AlpineLinux (Dermot Bradley), who investigated SSH
   alternatives like dropbearSSH and tinySSH, and FreeBSD (Mina Galić), who
@@ -124,15 +124,15 @@ Round-table discussions
 * **Shared test frameworks**: Azure intends to invest in integration testing
   with the cloud-init community, to develop distribution-agnostic best
   practices for verification of distribution releases, and boot-speed and image
-  health analysis. If there are ways we want to collaborate on generalised
+  health analysis. If there are ways we want to collaborate on generalized
   testing and verification of images, they may provide some development toward
   this cause.
 
 Breakout sessions
 -----------------
 
 * **Private reviews of partner engagements** with Oracle and AWS, and Fabio
-  Martins, Kyler Horner, and James to prioritise ongoing work and plan for the
+  Martins, Kyler Horner, and James to prioritize ongoing work and plan for the
   future development of IPv6-only datasource support - as well as other
   features.
 
@@ -166,7 +166,7 @@ Thank you!
 ==========
 
 This event could not have taken place without the hard work and preparation of
-all our presenters, organisers, and the voices of our community members in
+all our presenters, organizers, and the voices of our community members in
 attendance. So, thank you again to everyone who participated, and we very much
 hope to see you again at the next cloud-init summit!
 

doc/rtd/development/testing.rst

@@ -51,28 +51,14 @@ Test layout
 * ``pytest`` tests should use bare ``assert`` statements, to take advantage
   of ``pytest``'s `assertion introspection`_.
 
-``pytest`` version "gotchas"
-----------------------------
-
-As we still support Ubuntu 18.04 (Bionic Beaver), we can only use ``pytest``
-features that are available in v3.3.2. This is an inexhaustive list of
-ways in which this may catch you out:
-
-  * Only the following built-in fixtures are available [#fixture-list]_:
-
-    * ``cache``
-    * ``capfd``
-    * ``capfdbinary``
-    * ``caplog``
-    * ``capsys``
-    * ``capsysbinary``
-    * ``doctest_namespace``
-    * ``monkeypatch``
-    * ``pytestconfig``
-    * ``record_xml_property``
-    * ``recwarn``
-    * ``tmpdir_factory``
-    * ``tmpdir``
+Dependency versions
+-------------------
+
+Cloud-init supports a range of versions for each of its test dependencies, as
+well as runtime dependencies. If you are unsure whether a specific feature is
+supported for a particular dependency, check the ``lowest-supported``
+environment in ``tox.ini``. This can be run using ``tox -e lowest-supported``.
+This runs as a Github Actions job when a pull request is submitted or updated.
 
 Mocking and assertions
 ----------------------
@@ -139,13 +125,6 @@ Test argument ordering
   * ``pytest.mark.parametrize``
   * ``mock.patch``
 
-.. [#fixture-list] This list of fixtures (with markup) can be
-   reproduced by running::
-
-     python3 -m pytest  --fixtures -q | grep "^[^ -]" | grep -v 'no tests ran in' | sort | sed 's/ \[session scope\]//g;s/.*/* ``\0``/g'
-
-   in an ubuntu lxd container with python3-pytest installed.
-
 .. LINKS:
 .. _pytest: https://docs.pytest.org/
 .. _pytest fixtures: https://docs.pytest.org/en/latest/fixture.html