falconry · vytas7 · Mar 12, 2022 · Mar 11, 2022 · Mar 11, 2022 · Mar 11, 2022
diff --git a/AUTHORS b/AUTHORS
@@ -118,6 +118,7 @@ listed below by date of first contribution:
 * dimjon (dimucciojonathan)
 * signalw
 * Laurent Chriqui (laurent-chriqui)
+* Andrii Oriekhov (andriyor)
 
 (et al.)
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -0,0 +1,116 @@
+## Release Manager's Guide
+
+Release Process:
+
+1. Bump version and update tag.
+2. Update changelog and render towncrier fragments.
+3. Release beta or rc.
+4. Run benchmark and check for regressions.
+5. Review and edit doc changes since the last release for clarity and consistency.
+6. Publish final version and add a release note.
+7. Run benchmark and update falconframework.org with latest numbers.
+8. Announce the new version in Gitter channels and on the socials.
+
+### Bump version and update tag
+
+Modify `falcon/version.py` if it has not been updated since the previous
+release. Examine the rendered changelog to determine the appropriate SEMVER
+field to modify.
+
+Update changelog filename in `pyproject.toml` to suit.
+
+Update the build tag in `setup.cfg` under `[egg_info]` for pre-release builds,
+or remove it (leaving it blank as in `tag_build = `) for a final releases.
+
+### Update changelog and render towncrier fragments
+
+If a changelog RST has not yet been created, add one under `docs/changes` using
+the following template, and update the summary and changes to supported
+platforms to suit:
+
+```rst
+Changelog for Falcon 3.0.1
+==========================
+
+Summary
+-------
+
+This is a minor point release to take care of a couple of bugs that we did
+not catch for 3.0.0.
+
+Changes to Supported Platforms
+------------------------------
+
+- CPython 3.10 is now fully supported. (`#1966 <https://github.com/falconry/falcon/issues/1966>`__)
+- Support for Python 3.6 is now deprecated and will be removed in Falcon 4.0.
+- As with the previous release, Python 3.5 support remains deprecated and will
+  no longer be supported in Falcon 4.0.
+
+
+.. towncrier release notes start
+
+Contributors to this Release
+----------------------------
+
+Many thanks to those who contributed to this bugfix release:
+
+```
+
+Otherwise, ensure the summary has been brought up to date; be sure to highlight
+key changes in this release.
+
+Next update the contributors and render towncrier fragments by running:
+
+```sh
+$ tox -e changelog_release
+```
+
+Examine the updated RST as well as the rendered HTML docs and make any
+adjustments as needed. On OS X it's as simple as:
+
+```sh
+$ open docs/_build/html/changes/index.html
+```
+
+Or on Linux:
+
+```sh
+$ xdg-open docs/_build/html/changes/index.html
+```
+
+If you need to go back and make any additional tweaks:
+
+```sh
+$ git restore docs/changes
+```
+
+Then re-run the `tox` command when you're ready for another
+proofreading. Or if you just made a manual edit to the updated RST,
+you can re-render the docs without overwriting the changelog RST:
+
+```sh
+$ tox -e docs
+```
+
+Finally, if all looks good, remove the rendered towncrier fragments from
+`docs/_newsfragments` and then submit a PR containing the changes made so far.
+
+### Release beta or rc
+
+Be sure to install and test from PyPI as a sanity check afterwards. Fix docs,
+performance regressions, and reported bugs (if any) and release additional
+betas or release candidates.
+
+### Run benchmark and check for regressions
+
+TODO: Replace with CI gate
+
+### Review and edit doc changes since the last release for clarity and consistency
+
+### Publish final version and add a release note
+
+Be sure to install and test from PyPI as a sanity check afterwards.
+
+### Run benchmark and update falconframework.org with latest numbers
+
+### Announce the new version in Gitter channels and on the socials.
diff --git a/docs/_newsfragments/1320.newandimproved.rst b/docs/_newsfragments/1320.newandimproved.rst
diff --git a/docs/_newsfragments/1806.newandimproved.rst b/docs/_newsfragments/1806.newandimproved.rst
diff --git a/docs/_newsfragments/1858.newandimproved.rst b/docs/_newsfragments/1858.newandimproved.rst
diff --git a/docs/_newsfragments/1943.bugfix.rst b/docs/_newsfragments/1943.bugfix.rst
diff --git a/docs/_newsfragments/1951.newandimproved.rst b/docs/_newsfragments/1951.newandimproved.rst
diff --git a/docs/_newsfragments/1962.newandimproved.rst b/docs/_newsfragments/1962.newandimproved.rst
diff --git a/docs/_newsfragments/1963.bugfix.rst b/docs/_newsfragments/1963.bugfix.rst
diff --git a/docs/_newsfragments/1967.misc.rst b/docs/_newsfragments/1967.misc.rst
diff --git a/docs/_newsfragments/1991.newandimproved.rst b/docs/_newsfragments/1991.newandimproved.rst
diff --git a/docs/_newsfragments/2010.newandimproved.rst b/docs/_newsfragments/2010.newandimproved.rst
diff --git a/docs/_newsfragments/2024.bugfix.rst b/docs/_newsfragments/2024.bugfix.rst
diff --git a/docs/changes/3.1.0.rst b/docs/changes/3.1.0.rst
@@ -5,10 +5,21 @@ Changelog for Falcon 3.1.0
 Summary
 -------
 
-Falcon 3.1 is currently in development. You can track the progress here:
-`Version 3.1 <https://github.com/falconry/falcon/milestone/32>`__.
+This release contains several refinements to request validation and
+error handling, along with some tweaks to response handling for static and
+downloadable files.
 
-(See also the `Roadmap for Falcon 3.x <https://github.com/falconry/falcon/issues/1894>`__.)
+Due to popular demand, :class:`~falcon.testing.TestClient` and
+:class:`~falcon.testing.ASGIConductor` now expose convenience shorthand aliases
+for the ``simulate_*`` methods, i.e.,
+:func:`~falcon.testing.TestClient.simulate_get` is now also available as
+:func:`~falcon.testing.TestClient.get`, etc. (`#1806 <https://github.com/falconry/falcon/issues/1806>`__)
+
+Some important bugs were also fixed to ensure applications properly clean up
+response streams and do not hang when reading request bodies that are
+streamed using chunked transfer encoding.
+
+This release also adds support for CPython 3.10 and deprecates CPython 3.6.
 
 
 Changes to Supported Platforms
@@ -20,22 +31,89 @@ Changes to Supported Platforms
   no longer be supported in Falcon 4.0.
 
 
-.. towncrier release notes start
+New & Improved
+--------------
+
+- The :func:`jsonschema.validate <falcon.media.validators.jsonschema.validate>`
+  decorator now raises an instance of :class:`~falcon.MediaValidationError`
+  instead of the generic :class:`~falcon.HTTPBadRequest` for request media
+  validation failures. Although the default behavior is kept unaltered in a
+  backwards-compatible fashion (as the specialized exception subclasses the
+  generic one), but it can now be easily customized by adding an error handler
+  for the new class. (`#1320 <https://github.com/falconry/falcon/issues/1320>`__)
+- Due to popular demand, :class:`~falcon.testing.TestClient` and
+  :class:`~falcon.testing.ASGIConductor` now expose convenience shorthand aliases
+  for the ``simulate_*`` methods, i.e.,
+  :func:`~falcon.testing.TestClient.simulate_get` is now also available as
+  :func:`~falcon.testing.TestClient.get`, etc. (`#1806 <https://github.com/falconry/falcon/issues/1806>`__)
+- The :attr:`Request.range <falcon.Request.range>` property now has stricter
+  validation:
+
+    * When parsing a byte-range-spec with a last-byte-pos, it must be greater
+      than or equal to first-byte-pos.
+    * When parsing a suffix-byte-range-spec, suffix-length must be positive.
+
+  :func:`Static routes <falcon.App.add_static_route>` now support ``Range``
+  requests. This is useful for streaming media and resumable downloads. (`#1858 <https://github.com/falconry/falcon/issues/1858>`__)
+- Added a :attr:`Response.viewable_as <falcon.Response.viewable_as>` property;
+  this is similar to :attr:`Response.downloadable_as <falcon.Response.downloadable_as>`
+  but with an "inline" disposition type so the response will still be displayed
+  in the browser. (`#1951 <https://github.com/falconry/falcon/issues/1951>`__)
+- Added support for passing :any:`pathlib.Path` objects as `directory` in the
+  :func:`~falcon.App.add_static_route` method on all targeted Python versions. (`#1962 <https://github.com/falconry/falcon/issues/1962>`__)
+- :func:`Static routes <falcon.App.add_static_route>` now set the
+  ``Content-Length`` header indicating a served file's size
+  (or length of the rendered content range). (`#1991 <https://github.com/falconry/falcon/issues/1991>`__)
+- When called with deprecated positional arguments, methods and class
+  initializers (such as :class:`falcon.errors.HTTPError`) will now emit a
+  user-friendlier warning indicating the fully qualified name of the method in
+  question. (`#2010 <https://github.com/falconry/falcon/issues/2010>`__)
+
+
+Fixed
+-----
+
+- If provided, the ``close()`` method of an ASGI
+  :attr:`resp.stream <falcon.asgi.Response.stream>` is now guaranteed to be
+  called even in the case of an exception raised while iterating over the data. (`#1943 <https://github.com/falconry/falcon/issues/1943>`__)
+- Previously, files could be left open when serving via an ASGI static route
+  (depending on the underlying GC implementation). This has been fixed so that a
+  file is closed explicitly after rendering the response. (`#1963 <https://github.com/falconry/falcon/issues/1963>`__)
+- When a request was streamed using the chunked transfer encoding (with no
+  ``Content-Length`` known in advance), iterating over
+  :attr:`req.stream <falcon.asgi.Request.stream>` could hang until the client had
+  disconnected. This bug has been fixed, and iteration now stops upon receiving
+  the last body chunk as expected. (`#2024 <https://github.com/falconry/falcon/issues/2024>`__)
+
+
+Misc
+----
+
+- The :func:`~falcon.routing.compile_uri_template` utility method has been
+  deprecated and will be removed in Falcon 4.0. This function was only employed
+  in the early versions of the framework, and is expected to have been fully
+  supplanted by the :class:`~falcon.routing.CompiledRouter`. In the unlikely case
+  it is still in active use, its source code can be simply copied into an
+  affected application. (`#1967 <https://github.com/falconry/falcon/issues/1967>`__)
+
+
 
 
 Contributors to this Release
 ----------------------------
 
-Many thanks to contributors for this release (so far):
+Many thanks to all the contributors for this release!
 
 - `abidahmadq <https://github.com/abidahmadq>`__
+- `andriyor <https://github.com/andriyor>`__
 - `CaselIT <https://github.com/CaselIT>`__
 - `Contessina <https://github.com/Contessina>`__
 - `dflss <https://github.com/dflss>`__
 - `dimucciojonathan <https://github.com/dimucciojonathan>`__
 - `forana <https://github.com/forana>`__
 - `kgriffs <https://github.com/kgriffs>`__
 - `laurent-chriqui <https://github.com/laurent-chriqui>`__
+- `maxking <https://github.com/maxking>`__
 - `mgorny <https://github.com/mgorny>`__
 - `mihaitodor <https://github.com/mihaitodor>`__
 - `nix010 <https://github.com/nix010>`__

diff --git a/setup.cfg b/setup.cfg
@@ -74,7 +74,7 @@ console_scripts =
 
 [egg_info]
 # TODO replace
-tag_build = dev1
+tag_build = rc1
 
 [aliases]
 test=pytest

diff --git a/tools/towncrier_draft.py b/tools/towncrier_draft.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python
 
+import argparse
 import atexit
 import pathlib
 import subprocess
@@ -18,15 +19,11 @@ def _write_changelog(target, data):
 def get_target_filename():
     with open(ROOT / 'pyproject.toml') as pyproject_toml:
         project = toml.load(pyproject_toml)
-    return project['tool']['towncrier']['filename']
 
+    return project['tool']['towncrier']['filename']
 
-def render_draft(target):
-    with open(ROOT / target, 'rb') as rst:
-        template = rst.read()
-    # NOTE(vytas): Restore the template once we are done.
-    atexit.register(_write_changelog, target, template)
 
+def render_draft(target, template):
     draft = subprocess.check_output(('towncrier', '--draft'), cwd=ROOT)
 
     # NOTE(vytas): towncrier does not seem to respect our preference for not
@@ -38,6 +35,8 @@ def render_draft(target):
     # NOTE(vytas): towncrier --draft does not seem to use the template,
     #   so we substitute manually.
     rendered = template.replace(b'.. towncrier release notes start', draft, 1)
+
+    print(f'Writing changelog to {target}')
     _write_changelog(target, rendered)
 
 
@@ -55,7 +54,27 @@ def build_docs():
     )
 
 
-if __name__ == '__main__':
+def main():
+    description = (
+        'Render towncrier news fragments and write them to the changelog template.'
+    )
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument(
+        '-n', '--dry-run', action='store_true', help='dry run: do not write any files'
+    )
+    args = parser.parse_args()
+
     target = get_target_filename()
-    render_draft(target)
+    with open(ROOT / target, 'rb') as rst:
+        template = rst.read()
+
+    if args.dry_run:
+        # NOTE(vytas): Restore the template once we are done.
+        atexit.register(_write_changelog, target, template)
+
+    render_draft(target, template)
     build_docs()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tox.ini b/tox.ini
@@ -407,6 +407,14 @@ deps = -r{toxinidir}/requirements/docs
         toml
         towncrier
 commands =
+    {toxinidir}/tools/towncrier_draft.py --dry-run
+
+[testenv:changelog_release]
+deps = -r{toxinidir}/requirements/docs
+        toml
+        towncrier
+commands =
+    {toxinidir}/tools/add_contributors.py
     {toxinidir}/tools/towncrier_draft.py
 
 [testenv:dash]