From 2afcf9959124ee906b65569e7e4ae0ffb47e88a3 Mon Sep 17 00:00:00 2001
From: ibaker <ibaker@google.com>
Date: Tue, 11 Jul 2023 11:57:13 +0100
Subject: [PATCH] Expand `@UnstableApi` javadoc with how to request stable API
 additions

Issue: androidx/media#503

#minor-release

PiperOrigin-RevId: 547143885
---
 .../java/androidx/media3/common/util/UnstableApi.java    | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java b/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
index e4a7f5c20e..3ea66b64ad 100644
--- a/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
+++ b/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
@@ -41,6 +41,15 @@ import java.lang.annotation.Target;
  * work during upgrades. However it is generally inadvisable for libraries (which get included on
  * users' CLASSPATHs, outside the library developers' control) to do so.
  *
+ * <h2>Requesting additions to the stable API</h2>
+ *
+ * The Media3 stable API (i.e. those public API symbols that are not annotated with this annotation)
+ * is designed to allow developers to achieve common media-related tasks. If you have a use-case
+ * that you are unable to achieve using the stable API, and think you should be able to, please file
+ * an issue on our <a href="https://github.com/androidx/media/issues">GitHub issue tracker</a> with
+ * the full context of what you're doing, and what symbols you would need to be part of the stable
+ * API. We will consider each request on a case-by-case basis.
+ *
  * <h2>Opting in to use unstable APIs</h2>
  *
  * <p>By default usages of APIs annotated with this annotation generate lint errors in Gradle and