diff --git a/README.rst b/README.rst index e3620546a0..f62c2a37af 100644 --- a/README.rst +++ b/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 `__. -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 -`__ 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 `__ for advance +notice of any compatibility updates. Where to next? diff --git a/docs/source/code-of-conduct.rst b/docs/source/code-of-conduct.rst index 5d20cc3263..4e3fba3f9e 100644 --- a/docs/source/code-of-conduct.rst +++ b/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 `__, via `email `__ or any other medium that you feel comfortable with. Using words like "Trio code of conduct" in your subject will help make sure your diff --git a/docs/source/history.rst b/docs/source/history.rst index 6564164da3..24d4be7533 100644 --- a/docs/source/history.rst +++ b/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 `__. 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 `__ 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. diff --git a/docs/source/index.rst b/docs/source/index.rst index b89bc4533c..fea472424e 100644 --- a/docs/source/index.rst +++ b/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 -`__ 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 `__ to get a warning +and a chance to give feedback about any compatibility-breaking changes. Vital statistics: diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst index a21a6dec34..efab743dc9 100644 --- a/docs/source/reference-core.rst +++ b/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 diff --git a/newsfragments/3216.doc.rst b/newsfragments/3216.doc.rst new file mode 100644 index 0000000000..bce507194c --- /dev/null +++ b/newsfragments/3216.doc.rst @@ -0,0 +1 @@ +Update wording in documentation to more accurately reflect Trio's maturity. diff --git a/pyproject.toml b/pyproject.toml index ffc93e170f..6e6a946845 100644 --- a/pyproject.toml +++ b/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", diff --git a/src/trio/_deprecate.py b/src/trio/_deprecate.py index 51c51f7378..e5a157908e 100644 --- a/src/trio/_deprecate.py +++ b/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 `__ 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. """