feat: add deprecation warning for legacy_stderr_threshold_behavior

[pierluigilenoci]

Summary

Add a one-time deprecation warning when -stderrthreshold is explicitly set but silently ignored because -legacy_stderr_threshold_behavior=true (the current default).

This is the first step in a deprecation timeline, as discussed in #436 and kubernetes-sigs/metrics-server#1782:

1. This release: deprecation warning when legacy mode ignores -stderrthreshold
2. Future release: flip legacy_stderr_threshold_behavior default to false

What changed

• stderrThresholdValue wrapper type: wraps severityValue and tracks whether -stderrthreshold was explicitly set by the user via flag parsing or flagset.Set()
• One-time deprecation warning: emitted via fmt.Fprintf(os.Stderr, ...) on the first log call when both conditions are met:
  1. legacy_stderr_threshold_behavior=true (the current default)
  2. -stderrthreshold was explicitly set by the user
• Updated flag descriptions: mark legacy behavior as deprecated with a note about the future default change
• Updated package documentation: reflects the deprecation timeline

What did NOT change

• No default changes: legacy_stderr_threshold_behavior still defaults to true, stderrthreshold still defaults to ERROR
• No behavioral changes: the warning is purely informational; all existing logging behavior is preserved
• No breaking changes: consumers that don't explicitly set -stderrthreshold see no difference at all

Warning output

When triggered, the warning looks like:

WARNING: -stderrthreshold is set but ignored because -legacy_stderr_threshold_behavior=true (the current default). Set -legacy_stderr_threshold_behavior=false to honor -stderrthreshold when -logtostderr=true. The default for -legacy_stderr_threshold_behavior will change to false in a future klog release.

Historical context

A previous attempt to flip the defaults directly was reverted in #50 (2019) because it violated the Kubernetes deprecation policy. This PR takes the gradual approach: warn first, flip later.

Test plan

• TestLegacyBehaviorDeprecationWarning — verifies warning fires only when legacy=true AND stderrthreshold explicitly set
• TestCommandLine — updated to match new flag descriptions
• All existing tests pass (only pre-existing TestHeaderWithDir fails due to clone directory name)

Ref #436

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: pierluigilenoci
Once this PR has been reviewed and has the lgtm label, please assign dims for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

This issue is currently awaiting triage.

If klog contributors determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[pohly]

/hold

Let's discuss in #436.