Merge pull request #3216 from python-trio/update-readme-stability

Update stability info in documentation

README.rst

@@ -56,13 +56,13 @@ I/O-oriented programs easier, less error-prone, and just plain more
 fun. `Perhaps you'll find the same
 <https://github.com/python-trio/trio/wiki/Testimonials>`__.
 
-This project is young and still somewhat experimental: the overall
-design is solid, and the existing features are fully tested and
-documented, but you may encounter missing functionality or rough
-edges. We *do* encourage you to use it, but you should `read and
-subscribe to issue #1
-<https://github.com/python-trio/trio/issues/1>`__ to get a warning and a
-chance to give feedback about any compatibility-breaking changes.
+Trio is a mature and well-tested project: the overall design is solid,
+and the existing features are fully documented and widely used in
+production. While we occasionally make minor interface adjustments,
+breaking changes are rare. We encourage you to use Trio with confidence,
+but if you rely on long-term API stability, consider `subscribing to
+issue #1 <https://github.com/python-trio/trio/issues/1>`__ for advance
+notice of any compatibility updates.
 
 
 Where to next?

docs/source/code-of-conduct.rst

@@ -138,9 +138,9 @@ members. This section covers actual concrete steps.
 Contacting Maintainers
 ~~~~~~~~~~~~~~~~~~~~~~
 
-As a small and young project, we don't yet have a Code of Conduct
-enforcement team. Hopefully that will be addressed as we grow, but for
-now, any issues should be addressed to `Nathaniel J. Smith
+As a small project, we don't have a Code of Conduct enforcement team.
+Hopefully that will be addressed as we grow, but for now, any issues
+should be addressed to `Nathaniel J. Smith
 <https://github.com/njsmith>`__, via `email <mailto:[email protected]>`__
 or any other medium that you feel comfortable with. Using words like
 "Trio code of conduct" in your subject will help make sure your

docs/source/history.rst

@@ -1504,14 +1504,14 @@ Highlights
 Breaking changes and deprecations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Trio is a young and ambitious project, but it also aims to become a
-stable, production-quality foundation for async I/O in Python.
-Therefore, our approach for now is to provide deprecation warnings
-where-ever possible, but on a fairly aggressive cycle as we push
-towards stability. If you use Trio you should `read and subscribe to
-issue #1 <https://github.com/python-trio/trio/issues/1>`__. We'd also
-welcome feedback on how this approach is working, whether our
-deprecation warnings could be more helpful, or anything else.
+Trio has matured into a stable, production-quality foundation for
+async I/O in Python. While we strive to maintain stability, we may
+make occasional breaking changes to improve the library. Whenever
+possible, we provide deprecation warnings on a reasonable timeline to
+ease transitions. If you use Trio, we recommend `subscribing to issue
+#1 <https://github.com/python-trio/trio/issues/1>`__ to stay informed
+about changes. We also welcome feedback on how our deprecation process
+is working and whether it could be improved.
 
 The tl;dr is: stop using ``socket.bind`` if you can, and then fix
 everything your test suite warns you about.

docs/source/index.rst

@@ -33,13 +33,13 @@ the Python I/O library I always wanted; I find it makes building
 I/O-oriented programs easier, less error-prone, and just plain more
 fun. Perhaps you'll find the same.
 
-This project is young and still somewhat experimental: the overall
-design is solid and the existing features are fully tested and
-documented, but you may encounter missing functionality or rough
-edges. We *do* encourage you do use it, but you should `read and
-subscribe to issue #1
-<https://github.com/python-trio/trio/issues/1>`__ to get warning and a
-chance to give feedback about any compatibility-breaking changes.
+Trio is a mature and well-tested library, though it retains its
+“experimental” classification to allow for occasional breaking API
+changes as we push toward a 1.0 release. In practice, such changes are
+rare and typically minor. It is widely used in production environments,
+and we *do* encourage you do use it, but consider `subscribing to issue
+#1 <https://github.com/python-trio/trio/issues/1>`__ to get a warning
+and a chance to give feedback about any compatibility-breaking changes.
 
 Vital statistics:
 

docs/source/reference-core.rst

@@ -817,10 +817,10 @@ inside the handler function(s) with the ``nonlocal`` keyword:
 Designing for multiple errors
 +++++++++++++++++++++++++++++
 
-Structured concurrency is still a young design pattern, but there are a few patterns
-we've identified for how you (or your users) might want to handle groups of exceptions.
-Note that the final pattern, simply raising an `ExceptionGroup`, is the most common -
-and nurseries automatically do that for you.
+Structured concurrency is still a relatively new design pattern, but there are a few
+approaches we've identified for how you (or your users) might want to handle groups of
+exceptions. Note that the final pattern, simply raising an `ExceptionGroup`, is the most
+common - and nurseries automatically do that for you.
 
 **First**, you might want to 'defer to' a particular exception type, raising just that if
 there is any such instance in the group.  For example: `KeyboardInterrupt` has a clear

newsfragments/3216.doc.rst

@@ -0,0 +1 @@
+Update wording in documentation to more accurately reflect Trio's maturity.

pyproject.toml

@@ -14,7 +14,7 @@ keywords = [
     "trio",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Framework :: Trio",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",

src/trio/_deprecate.py

@@ -26,18 +26,18 @@
 class TrioDeprecationWarning(FutureWarning):
     """Warning emitted if you use deprecated Trio functionality.
 
-    As a young project, Trio is currently quite aggressive about deprecating
-    and/or removing functionality that we realize was a bad idea. If you use
-    Trio, you should subscribe to `issue #1
+    While a relatively mature project, Trio remains committed to refining its
+    design and improving usability. As part of this, we occasionally deprecate
+    or remove functionality that proves suboptimal. If you use Trio, we
+    recommend `subscribing to issue #1
     <https://github.com/python-trio/trio/issues/1>`__ to get information about
     upcoming deprecations and other backwards compatibility breaking changes.
 
     Despite the name, this class currently inherits from
-    :class:`FutureWarning`, not :class:`DeprecationWarning`, because while
-    we're in young-and-aggressive mode we want these warnings to be visible by
-    default. You can hide them by installing a filter or with the ``-W``
-    switch: see the :mod:`warnings` documentation for details.
-
+    :class:`FutureWarning`, not :class:`DeprecationWarning`, because until a
+    1.0 release, we want these warnings to be visible by default. You can hide
+    them by installing a filter or with the ``-W`` switch: see the
+    :mod:`warnings` documentation for details.
     """