Merge pull request #154 from incertum/deprecation/help-unit-required-future

refactor(API): deprecate non-descriptor metric creation methods

Author: incertum

.github/workflows/main.yml

@@ -14,10 +14,10 @@ jobs:
     name: Unit tests
     uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
     with:
-      linux_5_9_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
-      linux_5_10_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
-      linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
-      linux_nightly_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_6_1_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_6_2_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
       linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
 
   release-builds:

.github/workflows/pull_request.yml

@@ -16,10 +16,10 @@ jobs:
     name: Unit tests
     uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
     with:
-      linux_5_9_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
-      linux_5_10_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
-      linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
-      linux_nightly_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_6_1_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_6_2_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
+      linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
       linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
 
   benchmarks:

Sources/Prometheus/MetricDescriptor.swift

@@ -27,27 +27,25 @@ public struct MetricNameDescriptor {
     /// The required, descriptive base name of the metric.
     public let metricName: String
 
-    /// An optional suffix describing the metric's unit (e.g., `total`).
+    /// The required suffix describing the metric's unit (e.g., `total`).
     public let unitName: String?
 
-    /// Optional help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
-    /// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
+    /// The required help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
     public let helpText: String?
 
     /// Creates a new ``MetricNameDescriptor`` that defines the components of a fully qualified Prometheus metric name.
     ///
     /// - Parameter namespace: An optional top-level namespace for the metric.
     /// - Parameter subsystem: An optional subsystem to group related metrics within a namespace.
     /// - Parameter metricName: The required, descriptive base name of the metric.
-    /// - Parameter unitName: An optional suffix describing the metric's unit (e.g., `total`).
-    /// - Parameter helpText: Optional help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
-    ///                       If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
+    /// - Parameter unitName: The required suffix describing the metric's unit (e.g., `total`).
+    /// - Parameter helpText: The required help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
     public init(
         namespace: String? = nil,
         subsystem: String? = nil,
         metricName: String,
-        unitName: String? = nil,
-        helpText: String? = nil
+        unitName: String,
+        helpText: String
     ) {
         precondition(!metricName.isEmpty, "metricName must not be empty")
         self.namespace = namespace
@@ -64,3 +62,36 @@ public struct MetricNameDescriptor {
             .joined(separator: "_")
     }
 }
+
+// MARK: - Deprecated
+
+extension MetricNameDescriptor {
+    /// Creates a new ``MetricNameDescriptor`` that defines the components of a fully qualified Prometheus metric name.
+    ///
+    /// - Parameter namespace: An optional top-level namespace for the metric.
+    /// - Parameter subsystem: An optional subsystem to group related metrics within a namespace.
+    /// - Parameter metricName: The required, descriptive base name of the metric.
+    /// - Parameter unitName: An optional suffix describing the metric's unit (e.g., `total`).
+    /// - Parameter helpText: Optional help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
+    ///                       If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
+    @available(
+        *,
+        deprecated,
+        message: "This initializer is deprecated; 'unitName' and 'helpText' are now required parameters."
+    )
+    public init(
+        namespace: String? = nil,
+        subsystem: String? = nil,
+        metricName: String,
+        unitName: String? = nil,
+        helpText: String? = nil
+    ) {
+        self.init(
+            namespace: namespace,
+            subsystem: subsystem,
+            metricName: metricName,
+            unitName: unitName ?? "",
+            helpText: helpText ?? ""
+        )
+    }
+}