🧪 Add trl.experimental Submodule

README.md

@@ -190,6 +190,18 @@ cd trl/
 pip install -e .[dev]
 ```
 
+## Experimental
+
+A minimal incubation area is available under `trl.experimental` for unstable / fast-evolving features. Anything there may change or be removed in any release without notice.
+
+Example:
+
+```python
+from trl.experimental.new_trainer import NewTrainer
+```
+
+Read more in the [Experimental docs](https://huggingface.co/docs/trl/main/en/experimental).
+
 ## Citation
 
 ```bibtex

docs/source/_toctree.yml

@@ -11,6 +11,8 @@
     title: Dataset Formats
   - local: paper_index
     title: Paper Index
+  - local: experimental
+    title: Experimental
   - local: how_to_train
     title: Training FAQ
   - local: logging

docs/source/experimental.md

@@ -0,0 +1,51 @@
+# Experimental Features
+
+The `trl.experimental` namespace provides a minimal, clearly separated space for fast iteration on new ideas.
+
+<Tip warning={true}>
+
+**Stability contract:** Anything under `trl.experimental` may change or be removed in *any* release (including patch versions) without prior deprecation. Do not rely on these APIs for production workloads.
+
+</Tip>
+
+## Current Experimental Features
+
+The following modules are currently available under [`trl.experimental`](https://github.com/huggingface/trl/tree/main/trl/experimental).
+This list is not exhaustive and may change at any time.
+
+### Nothing here yet
+
+...
+
+## Usage
+
+```python
+from trl.experimental.new_trainer import NewTrainer
+```
+
+To silence the runtime notice:
+
+```bash
+export TRL_EXPERIMENTAL_SILENCE=1
+```
+
+## Promotion Path (Simple)
+
+1. **Prototype outside the main repo:** Start development in your own fork or a separate repository to iterate quickly.
+2. **Experimental inclusion:** Once it’s ready for early users, move the idea into `trl.experimental.<feature>`.
+3. **Improve:** Add tests, a short doc/example, and demonstrate the usage.
+4. **Promote:** Once the API proves stable and there is clear interest or adoption from the community, move it into `trl.<feature>` (stable module).
+
+## FAQ
+
+**Why not just use branches?**
+Because branches are not shipped to users; experimental code inside the package lets early adopters try things and give feedback.
+
+**Can these APIs change or vanish without warning?**
+Yes. Anything inside `trl.experimental` can change or disappear in *any* release.
+
+**Should I use this in production?**
+Only if you are fine with updating your code quickly when things change.
+
+**Will maintainers promptly fix issues in `trl.experimental`?**
+Not necessarily. The experimental module is a playground for new ideas, and maintainers may not prioritize bug fixes or feature requests there. Issues may remain unresolved until (or unless) the feature graduates to the stable API.

trl/experimental/__init__.py

@@ -0,0 +1,34 @@
+# Copyright 2020-2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Experimental submodule for TRL.
+
+This submodule contains unstable or incubating features. Anything here may change (or be removed) in any release
+without deprecation. Use at your own risk.
+
+To silence this notice set environment variable TRL_EXPERIMENTAL_SILENCE=1.
+"""
+
+import os
+import warnings
+
+
+if not os.environ.get("TRL_EXPERIMENTAL_SILENCE"):
+    warnings.warn(
+        "You are importing from 'trl.experimental'. APIs here are unstable and may change or be removed without "
+        "notice. Silence this warning by setting environment variable TRL_EXPERIMENTAL_SILENCE=1.",
+        UserWarning,
+        stacklevel=2,
+    )