Cleanup and add feature flag message

src/pip/_internal/utils/deprecation.py

@@ -11,14 +11,14 @@
 from pip import __version__ as current_version
 
 DEPRECATION_MESSAGE = "DEPRECATION: {reason}"
-DEPRECATION_GONE_IN_MESSAGE = (
-    "pip {gone_in} {remove_verb} support for this functionality."
-)
+GONE_IN_MESSAGE_FUTURE = "pip {gone_in} will enforce this behavior change."
+GONE_IN_MESSAGE_PAST = "This behavior change has been enforced since pip {gone_in}."
 REPLACEMENT_MESSAGE = "A possible replacement is {replacement}."
-ISSUE_MESSAGE = (
-    "You can find discussion regarding this at "
-    "https://github.com/pypa/pip/issues/{issue}."
+FEATURE_FLAG_MESSAGE = (
+    "You can temporarily use the flag --use-feature={feature_flag} "
+    "to test the upcoming behavior."
 )
+ISSUE_MESSAGE = "Discussion can be found at https://github.com/pypa/pip/issues/{issue}."
 
 
 class PipDeprecationWarning(Warning):
@@ -64,24 +64,24 @@ def deprecated(
     reason: str,
     replacement: Optional[str],
     gone_in: Optional[str],
-    gone_in_message: Optional[str] = DEPRECATION_GONE_IN_MESSAGE,
+    feature_flag: Optional[str] = None,
     issue: Optional[int] = None,
 ) -> None:
     """Helper to deprecate existing functionality.
 
     reason:
         Textual reason shown to the user about why this functionality has
-        been deprecated.
+        been deprecated. Should be a complete sentence.
     replacement:
         Textual suggestion shown to the user about what alternative
         functionality they can use.
     gone_in:
         The version of pip does this functionality should get removed in.
-        Raises errors if pip's current version is greater than or equal to
+        Raises an error if pip's current version is greater than or equal to
         this.
-    gone_in_message:
-        Template for a textual representation of the pip version when this
-        functionality will be (or has been) removed.
+    feature_flag:
+        Command-line flag of the form --use-feature={feature_flag} for testing
+        upcoming functionality.
     issue:
         Issue number on the tracker that would serve as a useful place for
         users to find related discussion and provide feedback.
@@ -91,21 +91,31 @@ def deprecated(
     """
     # Determine whether or not the feature is already gone in this version.
     is_gone = gone_in is not None and parse(current_version) >= parse(gone_in)
-    # Use the correct verb tense depending on whether or not the feature is already
-    # gone.
-    remove_verb = "has removed" if is_gone else "will remove"
-    # Allow variable substitutions for the "reason" variable.
+    # Allow variable substitutions within the "reason" variable.
     formatted_reason = reason.format(gone_in=gone_in)
     # Construct a nice message.
     #   This is eagerly formatted as we want it to get logged as if someone
     #   typed this entire message out.
+    formatted_deprecation_message = DEPRECATION_MESSAGE.format(reason=formatted_reason)
+    gone_in_message = GONE_IN_MESSAGE_PAST if is_gone else GONE_IN_MESSAGE_FUTURE
+    formatted_gone_in_message = (
+        gone_in_message.format(gone_in=gone_in) if gone_in else None
+    )
+    formatted_replacement_message = (
+        REPLACEMENT_MESSAGE.format(replacement=replacement) if replacement else None
+    )
+    formatted_feature_flag_message = (
+        None
+        if is_gone or not feature_flag
+        else FEATURE_FLAG_MESSAGE.format(feature_flag=feature_flag)
+    )
+    formatted_issue_message = ISSUE_MESSAGE.format(issue=issue) if issue else None
     sentences = [
-        DEPRECATION_MESSAGE.format(formatted_reason),
-        gone_in_message.format(gone_in=gone_in, remove_verb=remove_verb)
-        if gone_in
-        else None,
-        REPLACEMENT_MESSAGE.format(replacement=replacement) if replacement else None,
-        ISSUE_MESSAGE.format(issue=issue) if issue else None,
+        formatted_deprecation_message,
+        formatted_gone_in_message,
+        formatted_replacement_message,
+        formatted_feature_flag_message,
+        formatted_issue_message,
     ]
     message = " ".join(sentence for sentence in sentences if sentence)