Экспериментальный

Эта директория содержит минимальное, чётко изолированное пространство для быстрой итерации над новыми идеями.

Договор о стабильности: Всё, что находится в trl.experimental, может измениться или быть удалено в любом выпуске (включая патч-версии) без предварительного объявления о снятии с поддержки. Не используйте эти API для производственных задач.

Путь продвижения (простой)

1. Прототипируйте вне основного репозитория: начинайте разработку в собственном форке или отдельном репозитории, чтобы быстро итерировать.
2. Экспериментальное включение: когда идея будет готова для ранних пользователей, перенесите её в trl.experimental.<feature>.
3. Улучшение: добавьте тесты, краткую документацию/пример и продемонстрируйте использование.
4. Продвижение: когда API доказывает свою стабильность и в сообществе возникает явный интерес или начинается его использование, перенесите его в trl.<feature> (стабильный модуль).

Удаление

Experimental — это промежуточная зона, а не место для долгосрочного хранения: функция либо продвигается, либо удаляется. Для удаления не требуется цикл устаревания, как указано в контракте стабильности выше. Код остаётся доступным в истории git, а запись в индексе статей сохраняется, указывая на последний релиз, в котором была выпущена реализация.

Порог, при котором происходит удаление, не задан. Это решение принимается в pull request на удаление, когда цифры видны всем. На что опирается это решение:

• Использование. Телеметрия, теги Hub и ответы в pull request или в ветке обсуждения. Ни один из этих показателей сам по себе не является окончательным, но если все они молчат, это сильный сигнал.
• Внешние проблемы и pull request, возникающие при использовании функции, в отличие от отчётов, полученных в результате сканирования кода.
• Покрыта ли задача уже стабильным тренером. Если да, это перевешивает частоту использования.
• Стоимость. Время CI, обслуживание, нагрузка на триаж.
• Потребители ниже по цепочке. Библиотеки, которые импортируют его.
• Владелец. Тот, кто хочет продвинуть проект и готов приложить к этому усилия.
• Возраст. Достаточно ли давно он доступен, чтобы сообщество успело его найти и протестировать.

Часто задаваемые вопросы

Почему бы просто не использовать ветки? Потому что ветки не поставляются пользователям; экспериментальный код внутри пакета позволяет ранним пользователям попробовать новые возможности и дать обратную связь.

Могут ли эти API измениться или исчезнуть без предупреждения? Да. Всё, что находится внутри trl.experimental, может измениться или исчезнуть в любом релизе.

Стоит ли использовать это в продакшене? Только если вы готовы оперативно обновлять код при изменениях.

Будут ли сопровождающие оперативно исправлять проблемы в trl.experimental? Не обязательно. Экспериментальный модуль служит полигоном для новых идей, и сопровождающие могут не придавать приоритета исправлению ошибок или реализации новых функций в нём. Проблемы могут оставаться нерешёнными до тех пор, пока (или если) функция не перейдёт в стабильный API.

Я добавил реализацию статьи. Можно ли её удалить? Да. Всё, что находится в trl.experimental, может быть удалено, включая реализации статей. Если это произойдёт, запись в индексе статей сохранится и будет указывать на последний релиз, в котором код был доступен.

Как отключить уведомление во время выполнения?

Использование: export TRL_EXPERIMENTAL_SILENCE=1.