Merge pull request #1521 from Nordix/tuomo/switch-to-markdownlint-cli2

📖 switch markdownlint container to markdownlint-cli2
metal3-io · Jan 24, 2024 · d6f67a8 · d6f67a8
2 parents 7358a8b + 4e466a4
commit d6f67a8
Show file tree

Hide file tree

Showing 9 changed files with 116 additions and 77 deletions.
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -0,0 +1,9 @@
+# Reference: https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2yaml
+
+config:
+  ul-indent:
+    # Kramdown wanted us to have 3 earlier, tho this CLI recommends 2 or 4
+    indent: 3
+
+# Don't autofix anything, we're linting here
+fix: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -41,8 +41,9 @@ Commit message should contain signed off section with full name and email. For e
   Signed-off-by: John Doe <[email protected]>
  ```
 
-When making commits, include the `-s` flag and `Signed-off-by` section will be automatically
-added to your commit message. If you want GPG signing too, add the `-S` flag alongside `-s`.
+When making commits, include the `-s` flag and `Signed-off-by` section
+will be automatically added to your commit message. If you want GPG
+signing too, add the `-S` flag alongside `-s`.
 
 ```bash
   # Signing off commit
@@ -112,10 +113,14 @@ the ability to backport and release patch versions;
 - The EOL date of each API Version is determined from the last release available
   once a new API version is published.
 
+<!-- markdownlint-disable MD013 -->
+
 | API Version  | Maintained Until                                              |
 | ------------ | ------------------------------------------------------------- |
 | **v1alpha1** | TBD (current latest)                                          |
-| **v1beta1**  | Upcoming (Proposal [PR](https://github.com/metal3-io/metal3-docs/pull/332))                                         |
+| **v1beta1**  | Upcoming (Proposal [PR](https://github.com/metal3-io/metal3-docs/pull/332)) |
+
+<!-- markdownlint-enable MD013 -->
 
 - For the current stable API version (v1alpha1) we support the two most recent
   minor releases; older minor releases are immediately unsupported when a new

diff --git a/docs/api.md b/docs/api.md
@@ -29,6 +29,8 @@ The sub-fields are
 BMC URLs vary based on the type of BMC and the protocol used to
 communicate with them.
 
+<!-- markdownlint-disable MD013 -->
+
 | Technology      | Protocol | Boot method   | Format                                            | Notes                                                                   |
 |-----------------|----------|---------------|---------------------------------------------------|-------------------------------------------------------------------------|
 | Generic IPMI    | IPMI     | iPXE          | `ipmi://<host>:<port>` or just `<host>:<port>`    | Port is optional, defaults to 623                                       |
@@ -45,6 +47,8 @@ communicate with them.
 |                 | Redfish  | iPXE          | `ilo5-redfish://<host>:<port>/<systemID>`         |                                                                         |
 |                 | Redfish  | Virtual media | `ilo5-virtualmedia://<host>:<port>/<systemID>`    |                                                                         |
 
+<!-- markdownlint-enable MD013 -->
+
 All protocols based on HTTPS (i.e. not IPMI) with an exception of iRMC allow
 optionally specifying the carrier protocol in the form of `+http` or `+https`,
 for example: `redfish+http://...` or `idrac-virtualmedia+https`. iLO (both
@@ -834,35 +838,44 @@ metadata:
 
 ## HardwareData
 
-A **HardwareData** resource contains hardware specifications data of a specific host
-and it is tightly coupled to its owner resource BareMetalHost. The data in the HardwareData
-comes from Ironic after a successful inspection phase. As such, operator will create HardwareData
-resource for a specific BareMetalHost during transitioning phase from inspecting into available
-state of the BareMetalHost. HardwareData gets deleted automatically by the operator whenever its
-BareMetalHost is deleted. Deprovisioning of the BareMetalHost should not trigger the deletion of
-HardwareData, but during next provisioning it can be re-created (with the same name and namespace)
-with the latest inspection data retrieved from Ironic. HardwareData holds the same name and namespace
-as its corresponding BareMetalHost resource. Currently, HardwareData doesn't have *Status* subresource
-but only the *Spec*, which we cover next.
+A **HardwareData** resource contains hardware specifications data of a
+specific host and it is tightly coupled to its owner resource
+BareMetalHost. The data in the HardwareData comes from Ironic after a
+successful inspection phase. As such, operator will create HardwareData
+resource for a specific BareMetalHost during transitioning phase from
+inspecting into available state of the BareMetalHost. HardwareData gets
+deleted automatically by the operator whenever its BareMetalHost is
+deleted. Deprovisioning of the BareMetalHost should not trigger the
+deletion of HardwareData, but during next provisioning it can be
+re-created (with the same name and namespace) with the latest inspection
+data retrieved from Ironic. HardwareData holds the same name and
+namespace as its corresponding BareMetalHost resource. Currently,
+HardwareData doesn't have *Status* subresource but only the *Spec*,
+which we cover next.
 
 ### HardwareData spec
 
-As you probably already noticed, the *Spec* of HardwareData is the same as [.Status.hardware](#hardware)
-of the BareMetalHost. However, this behaviour is temporary and eventually we will drop
-[.Status.hardware](#hardware) from BareMetalHost and only rely on HardwareData *Spec*. The reason
-for having duplication of inspection data at the  moment is to avoid breaking the existing deployments.
+As you probably already noticed, the *Spec* of HardwareData is the same
+as [.Status.hardware](#hardware) of the BareMetalHost. However, this
+behaviour is temporary and eventually we will drop
+[.Status.hardware](#hardware) from BareMetalHost and only rely on
+HardwareData *Spec*. The reason for having duplication of inspection
+data at the  moment is to avoid breaking the existing deployments.
 
 ## PreprovisioningImage
 
-A **PreprovisioningImage** resource is automatically created by baremetal-operator for each BareMetalHost
-to ensure creation of a *preprovisioning image* for it. In this context, a preprovisioning image
-is an ISO or initramfs file that contains the [Ironic agent](https://docs.openstack.org/ironic-python-agent/).
-The relevant parts of BareMetalHost are copied to the PreprovisioningImage *Spec*,
+A **PreprovisioningImage** resource is automatically created by
+baremetal-operator for each BareMetalHost to ensure creation of a
+*preprovisioning image* for it. In this context, a preprovisioning image
+is an ISO or initramfs file that contains the [Ironic
+agent](https://docs.openstack.org/ironic-python-agent/). The relevant
+parts of BareMetalHost are copied to the PreprovisioningImage *Spec*,
 the resulting image is expected to appear in the *Status*.
 
-The baremetal-operator project contains a simple controller for PreprovisioningImages
-that uses images provided in the environment variables `DEPLOY_ISO_URL` and `DEPLOY_RAMDISK_URL`.
-More sophisticated controllers may be written downstream (for example, the OpenShift
+The baremetal-operator project contains a simple controller for
+PreprovisioningImages that uses images provided in the environment
+variables `DEPLOY_ISO_URL` and `DEPLOY_RAMDISK_URL`. More sophisticated
+controllers may be written downstream (for example, the OpenShift
 [image-customization-controller](https://github.com/openshift/image-customization-controller)).
 
 ### PreprovisioningImage spec
@@ -874,24 +887,28 @@ The PreprovisioningImage's spec provides input for the image building process.
 * `architecture`: the CPU architecture to build the image for, e.g. `x86_64`.
   The default PreprovisioningImage controller does not use this field.
 
-* `networkData`: the name of a *Secret* with the network configuration for the image.
-  The default PreprovisioningImage controller does not use this field.
+* `networkData`: the name of a *Secret* with the network configuration
+  for the image. The default PreprovisioningImage controller does not
+  use this field.
 
 ### PreprovisioningImage status
 
 The PreprovisioningImage's status provides information about the resulting image.
 
 * `architecture`: the CPU architecture of the image, e.g. `x86_64`.
 
-* `extraKernelParams`: additional kernel parameters that baremetal-operator will add to the node
-  when PXE booting the initramfs image. Has no meaning for ISO images.
+* `extraKernelParams`: additional kernel parameters that
+  baremetal-operator will add to the node when PXE booting the initramfs
+  image. Has no meaning for ISO images.
 
-* `format`: format of the image: `iso` or `initrd`. Must be one of the formats provided in `acceptFormats`.
+* `format`: format of the image: `iso` or `initrd`. Must be one of the
+  formats provided in `acceptFormats`.
 
 * `imageUrl`: the URL of the resulting image.
 
-* `kernelUrl`: the URL of the kernel to use together with the initramfs image. If not provided,
-  baremetal-operator uses the default kernel image from the environment variables.
-  Has no meaning for ISO images.
+* `kernelUrl`: the URL of the kernel to use together with the initramfs
+  image. If not provided, baremetal-operator uses the default kernel
+  image from the environment variables. Has no meaning for ISO images.
 
-* `networkData`: the name of a *Secret* with the network configuration of the image.
+* `networkData`: the name of a *Secret* with the network configuration
+  of the image.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -42,9 +42,9 @@ but overflows could happen in case of slow provisioners and / or higher number o
 concurrent reconciles. For such reasons, it is highly recommended to keep
 BMO_CONCURRENCY value lower than the requested PROVISIONING_LIMIT. Default is 20.
 
-`IRONIC_EXTERNAL_URL_V6` -- This is the URL where Ironic will find the image for
-nodes that use IPv6. In dual stack environments, this can be used to tell Ironic which IP
-version it should set on the BMC.
+`IRONIC_EXTERNAL_URL_V6` -- This is the URL where Ironic will find the
+image for nodes that use IPv6. In dual stack environments, this can be
+used to tell Ironic which IP version it should set on the BMC.
 
 Kustomization Configuration
 ---------------------------

diff --git a/docs/deploying.md b/docs/deploying.md
@@ -136,11 +136,12 @@ ironic-deployment/
 └── README.md
 ```
 
-The `ironic-deployment` folder contains kustomizations for deploying Ironic.
-It makes use of kustomize components for basic auth, TLS and keepalived configurations.
-This makes it easy to combine the configurations, for example basic auth + TLS.
-There are some ready made overlays in the `overlays` folder that shows how this can be done.
-For more information, check the readme in the `ironic-deployment` folder.
+The `ironic-deployment` folder contains kustomizations for deploying
+Ironic. It makes use of kustomize components for basic auth, TLS and
+keepalived configurations. This makes it easy to combine the
+configurations, for example basic auth + TLS. There are some ready made
+overlays in the `overlays` folder that shows how this can be done. For
+more information, check the readme in the `ironic-deployment` folder.
 
 ## Deployment commands
 

diff --git a/docs/dev-setup.md b/docs/dev-setup.md
@@ -176,19 +176,25 @@ and specially the [Baremetal Operator Integration](https://github.com/metal3-io/
 
 ### Making (virtual) BareMetalHosts with Tilt interface
 
-Virtinst, libvirt-clients, libvirt-daemon-system, and [Virtualbmc](https://pypi.org/project/virtualbmc/) are required to to create BareMetalHosts this way. The network and VBMC needed for making a BareMetalHosts can be initialized with
+Virtinst, libvirt-clients, libvirt-daemon-system, and
+[Virtualbmc](https://pypi.org/project/virtualbmc/) are required to to
+create BareMetalHosts this way. The network and VBMC needed for making a
+BareMetalHosts can be initialized with
 
 ```sh
 tools/bmh_test/run_local_bmh_test_setup.sh
 ```
 
-When Tilt is up, it is possible to make BareMetalHosts by pressing a button in the Tilt localhost interface. This is currently only supported for Unix based systems. This button runs the content of file
+When Tilt is up, it is possible to make BareMetalHosts by pressing a
+button in the Tilt localhost interface. This is currently only supported
+for Unix based systems. This button runs the content of file
 
 ```sh
 tools/bmh_test/create_bmh.sh <NAME> <VBMC_PORT>
 ```
 
-and adds the values given to the button as arguments. Controlplane host can be created with
+and adds the values given to the button as arguments. Controlplane host
+can be created with
 
 ```sh
 tools/bmh_test/create_bmh.sh <NAME> <VBMC_PORT> <CONSUMER> <CONSUMER_NAMESPACE>

diff --git a/hack/markdownlint.sh b/hack/markdownlint.sh
@@ -1,31 +1,20 @@
-#!/bin/bash
-
-# TODO:
-# Fix these two failures in future commit, and remove the ignore rules
-#
-# Further documentation is available for these failures:
-# - MD029: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md#md029---ordered-list-item-prefix
-# - MD013: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md#md013---line-length
+#!/bin/sh
+# markdownlint-cli2 has config file(s) named .markdownlint-cli2.yaml in the repo
 
 set -eux
 
-IS_CONTAINER=${IS_CONTAINER:-false}
+IS_CONTAINER="${IS_CONTAINER:-false}"
 CONTAINER_RUNTIME="${CONTAINER_RUNTIME:-podman}"
 
+# all md files, but ignore .github
 if [ "${IS_CONTAINER}" != "false" ]; then
-  TOP_DIR="${1:-.}"
-  find "${TOP_DIR}" \
-       \( -path ./vendor -o -path ./.github \) \
-      -prune -o -name '*.md' -exec \
-      mdl --style all --warnings \
-      --rules "~MD013,~MD029" \
-      {} \+
+    markdownlint-cli2 "**/*.md" "#.github"
 else
-  "${CONTAINER_RUNTIME}" run --rm \
-    --env IS_CONTAINER=TRUE \
-    --volume "${PWD}:/workdir:ro,z" \
-    --entrypoint sh \
-    --workdir /workdir \
-    docker.io/pipelinecomponents/markdownlint:0.13.0@sha256:9c0cdfb64fd3f1d3bdc5181629b39c2e43b6a52fc9fdc146611e1860845bbae0 \
-    /workdir/hack/markdownlint.sh "$@"
+    "${CONTAINER_RUNTIME}" run --rm \
+        --env IS_CONTAINER=TRUE \
+        --volume "${PWD}:/workdir:ro,z" \
+        --entrypoint sh \
+        --workdir /workdir \
+        docker.io/pipelinecomponents/markdownlint-cli2:0.9.0@sha256:71370df6c967bae548b0bfd0ae313ddf44bfad87da76f88180eff55c6264098c \
+        /workdir/hack/markdownlint.sh "$@"
 fi
diff --git a/ironic-deployment/README.md b/ironic-deployment/README.md
@@ -1,13 +1,24 @@
 # Kustomizations for Ironic
 
-This folder contains kustomizations for Ironic.
-They are mainly used through the [deploy.sh](../tools/deploy.sh) script, which takes care of generating the necessary config for basic-auth and TLS.
+This folder contains kustomizations for Ironic. They are mainly used
+through the [deploy.sh](../tools/deploy.sh) script, which takes care of
+generating the necessary config for basic-auth and TLS.
 
 - **base** - This is the kustomize base that we start from.
-- **components** - In here you will find re-usable kustomize components for running Ironic with TLS, basic-auth, keepalived or mariadb.
-   - **basic-auth** - Enable basic authentication. Note that the basic-auth component is missing the actual credentials. This is on purpose, to make sure that the user is setting the password.
-   - **tls** - Enable TLS. The TLS component needs to have the proper IP/SAN set for the certificates.
-   - **keepalived** - Add a keepalived container to the deployment. This is useful when using a VIP for exposing the Ironic endpoint, so that the IP can move with the pod.
-   - **mariadb** - Use MariaDB instead of SQLite. TLS required for this to work.
-- **default** - A minimal, fully working, Ironic kustomization including configmap and password. Use only for development! The DB password is hard coded in the repo and there is no TLS or basic-auth.
-- **overlays** - Here you will find ready made overlays that use the above mentioned components.
+- **components** - In here you will find re-usable kustomize components
+  for running Ironic with TLS, basic-auth, keepalived or mariadb.
+   - **basic-auth** - Enable basic authentication. Note that the
+     basic-auth component is missing the actual credentials. This is on
+     purpose, to make sure that the user is setting the password.
+   - **tls** - Enable TLS. The TLS component needs to have the proper
+     IP/SAN set for the certificates.
+   - **keepalived** - Add a keepalived container to the deployment. This
+     is useful when using a VIP for exposing the Ironic endpoint, so
+     that the IP can move with the pod.
+   - **mariadb** - Use MariaDB instead of SQLite. TLS required for this
+     to work.
+- **default** - A minimal, fully working, Ironic kustomization including
+  configmap and password. Use only for development! The DB password is
+  hard coded in the repo and there is no TLS or basic-auth.
+- **overlays** - Here you will find ready made overlays that use the
+  above mentioned components.
diff --git a/test/e2e/README.md b/test/e2e/README.md
@@ -38,7 +38,8 @@ Ironic. Without any changes, the whole suite (including optional tests) will be
 Please note, however, that it is quite questionable to call this configuration
 "end to end".
 
-Fixture provider is configured to be the default one. This is how to run the e2e test suite with it:
+Fixture provider is configured to be the default one. This is how to run
+the e2e test suite with it:
 
 ```bash
 make test-e2e