From 030a1316653e04aafe1d4fff1c04cd9090d10cf4 Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Thu, 10 Mar 2022 21:37:32 -0700 Subject: [PATCH 1/5] chore: prep for 3.1.0 release --- AUTHORS | 1 + RELEASE.md | 109 +++++++++++++++++++++++++++++++++++++++ docs/changes/3.1.0.rst | 88 +++++++++++++++++++++++++++++-- setup.cfg | 2 +- tools/towncrier_draft.py | 35 ++++++++++--- tox.ini | 10 ++++ 6 files changed, 231 insertions(+), 14 deletions(-) create mode 100644 RELEASE.md diff --git a/AUTHORS b/AUTHORS index c0fb68efd..f148d78b0 100644 --- 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 new file mode 100644 index 000000000..6902a445d --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,109 @@ +## 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 `__) +- 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: + + $ 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: + +.. code:: bash + + $ open docs/_build/html/changes/index.html + +Or on Linux: + +.. code:: bash + + $ xdg-open docs/_build/html/changes/index.html + +If you need to go back and make any additional tweaks, just +`git restore docs/changes` and re-run the tox command when ready for another +proofreading. Or if you just made a manual edit to the changelog RST, +you can simply re-render the docs: + +.. code:: bash + + $ tox -e docs + +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/changes/3.1.0.rst b/docs/changes/3.1.0.rst index 389728484..982a0f145 100644 --- 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 `__. +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 `__.) +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 `__) + +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,15 +31,81 @@ Changes to Supported Platforms no longer be supported in Falcon 4.0. -.. towncrier release notes start +New & Improved +-------------- + +- The :func:`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 `__) +- 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 `__) +- The :attr:`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 ` now support ``Range`` + requests. This is useful for streaming media and resumable downloads. (`#1858 `__) +- Added a :attr:`Response.viewable_as ` property; + this is similar to :attr:`Response.downloadable_as ` + but with an "inline" disposition type so the response will still be displayed + in the browser. (`#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 `__) +- :func:`Static routes ` now set the + ``Content-Length`` header indicating a served file's size + (or length of the rendered content range). (`#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 `__) + + +Fixed +----- + +- If provided, the ``close()`` method of an ASGI + :attr:`resp.stream ` is now guaranteed to be + called even in the case of an exception raised while iterating over the data. (`#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 `__) +- When a request was streamed using the chunked transfer encoding (with no + ``Content-Length`` known in advance), iterating over + :attr:`req.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 `__) + + +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 `__) + + Contributors to this Release ---------------------------- -Many thanks to contributors for this release (so far): +Many thanks to all the contributors for this release! - `abidahmadq `__ +- `andriyor `__ - `CaselIT `__ - `Contessina `__ - `dflss `__ @@ -36,6 +113,7 @@ Many thanks to contributors for this release (so far): - `forana `__ - `kgriffs `__ - `laurent-chriqui `__ +- `maxking `__ - `mgorny `__ - `mihaitodor `__ - `nix010 `__ diff --git a/setup.cfg b/setup.cfg index 151e133c6..885a569db 100644 --- 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 index 2daacacdd..4a24b22fe 100755 --- 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 index ed54274ea..afeb21474 100644 --- a/tox.ini +++ b/tox.ini @@ -407,6 +407,16 @@ 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] From 41fb8ad3a2013ea462477e5fbcb1f00e18ddf967 Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Thu, 10 Mar 2022 21:48:12 -0700 Subject: [PATCH 2/5] style(pep8): single quotes fix --- tools/towncrier_draft.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/towncrier_draft.py b/tools/towncrier_draft.py index 4a24b22fe..daa6769d8 100755 --- a/tools/towncrier_draft.py +++ b/tools/towncrier_draft.py @@ -36,7 +36,7 @@ def render_draft(target, template): # so we substitute manually. rendered = template.replace(b'.. towncrier release notes start', draft, 1) - print(f"Writing changelog to {target}") + print(f'Writing changelog to {target}') _write_changelog(target, rendered) From 19038f25efba352cd7a89bd3000afa00ba74ae00 Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Fri, 11 Mar 2022 15:20:18 -0700 Subject: [PATCH 3/5] chore(docs): remove rendered towncrier news --- docs/_newsfragments/1320.newandimproved.rst | 7 ------- docs/_newsfragments/1806.newandimproved.rst | 5 ----- docs/_newsfragments/1858.newandimproved.rst | 9 --------- docs/_newsfragments/1943.bugfix.rst | 3 --- docs/_newsfragments/1951.newandimproved.rst | 4 ---- docs/_newsfragments/1962.newandimproved.rst | 2 -- docs/_newsfragments/1963.bugfix.rst | 3 --- docs/_newsfragments/1967.misc.rst | 6 ------ docs/_newsfragments/1991.newandimproved.rst | 3 --- docs/_newsfragments/2010.newandimproved.rst | 4 ---- docs/_newsfragments/2024.bugfix.rst | 5 ----- 11 files changed, 51 deletions(-) delete mode 100644 docs/_newsfragments/1320.newandimproved.rst delete mode 100644 docs/_newsfragments/1806.newandimproved.rst delete mode 100644 docs/_newsfragments/1858.newandimproved.rst delete mode 100644 docs/_newsfragments/1943.bugfix.rst delete mode 100644 docs/_newsfragments/1951.newandimproved.rst delete mode 100644 docs/_newsfragments/1962.newandimproved.rst delete mode 100644 docs/_newsfragments/1963.bugfix.rst delete mode 100644 docs/_newsfragments/1967.misc.rst delete mode 100644 docs/_newsfragments/1991.newandimproved.rst delete mode 100644 docs/_newsfragments/2010.newandimproved.rst delete mode 100644 docs/_newsfragments/2024.bugfix.rst diff --git a/docs/_newsfragments/1320.newandimproved.rst b/docs/_newsfragments/1320.newandimproved.rst deleted file mode 100644 index 1dc5d156e..000000000 --- a/docs/_newsfragments/1320.newandimproved.rst +++ /dev/null @@ -1,7 +0,0 @@ -The :func:`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. diff --git a/docs/_newsfragments/1806.newandimproved.rst b/docs/_newsfragments/1806.newandimproved.rst deleted file mode 100644 index 4e0ca910f..000000000 --- a/docs/_newsfragments/1806.newandimproved.rst +++ /dev/null @@ -1,5 +0,0 @@ -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. diff --git a/docs/_newsfragments/1858.newandimproved.rst b/docs/_newsfragments/1858.newandimproved.rst deleted file mode 100644 index cd8ea41b7..000000000 --- a/docs/_newsfragments/1858.newandimproved.rst +++ /dev/null @@ -1,9 +0,0 @@ -The :attr:`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 ` now support ``Range`` -requests. This is useful for streaming media and resumable downloads. diff --git a/docs/_newsfragments/1943.bugfix.rst b/docs/_newsfragments/1943.bugfix.rst deleted file mode 100644 index d313689dc..000000000 --- a/docs/_newsfragments/1943.bugfix.rst +++ /dev/null @@ -1,3 +0,0 @@ -If provided, the ``close()`` method of an ASGI -:attr:`resp.stream ` is now guaranteed to be -called even in the case of an exception raised while iterating over the data. diff --git a/docs/_newsfragments/1951.newandimproved.rst b/docs/_newsfragments/1951.newandimproved.rst deleted file mode 100644 index 3fec18f2f..000000000 --- a/docs/_newsfragments/1951.newandimproved.rst +++ /dev/null @@ -1,4 +0,0 @@ -Added a :attr:`Response.viewable_as ` property; -this is similar to :attr:`Response.downloadable_as ` -but with an "inline" disposition type so the response will still be displayed -in the browser. diff --git a/docs/_newsfragments/1962.newandimproved.rst b/docs/_newsfragments/1962.newandimproved.rst deleted file mode 100644 index 35b47b36b..000000000 --- a/docs/_newsfragments/1962.newandimproved.rst +++ /dev/null @@ -1,2 +0,0 @@ -Added support for passing :any:`pathlib.Path` objects as `directory` in the -:func:`~falcon.App.add_static_route` method on all targeted Python versions. diff --git a/docs/_newsfragments/1963.bugfix.rst b/docs/_newsfragments/1963.bugfix.rst deleted file mode 100644 index b917bc17f..000000000 --- a/docs/_newsfragments/1963.bugfix.rst +++ /dev/null @@ -1,3 +0,0 @@ -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. diff --git a/docs/_newsfragments/1967.misc.rst b/docs/_newsfragments/1967.misc.rst deleted file mode 100644 index 628545910..000000000 --- a/docs/_newsfragments/1967.misc.rst +++ /dev/null @@ -1,6 +0,0 @@ -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. diff --git a/docs/_newsfragments/1991.newandimproved.rst b/docs/_newsfragments/1991.newandimproved.rst deleted file mode 100644 index db1f6f627..000000000 --- a/docs/_newsfragments/1991.newandimproved.rst +++ /dev/null @@ -1,3 +0,0 @@ -:func:`Static routes ` now set the -``Content-Length`` header indicating a served file's size -(or length of the rendered content range). diff --git a/docs/_newsfragments/2010.newandimproved.rst b/docs/_newsfragments/2010.newandimproved.rst deleted file mode 100644 index b1eb33761..000000000 --- a/docs/_newsfragments/2010.newandimproved.rst +++ /dev/null @@ -1,4 +0,0 @@ -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. \ No newline at end of file diff --git a/docs/_newsfragments/2024.bugfix.rst b/docs/_newsfragments/2024.bugfix.rst deleted file mode 100644 index b72d6af48..000000000 --- a/docs/_newsfragments/2024.bugfix.rst +++ /dev/null @@ -1,5 +0,0 @@ -When a request was streamed using the chunked transfer encoding (with no -``Content-Length`` known in advance), iterating over -:attr:`req.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. From d859ecbbb8b11b8bbf4c64470fde2c50223e2ffd Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Fri, 11 Mar 2022 15:26:36 -0700 Subject: [PATCH 4/5] doc(RELEASE.md): fix bad formatting --- RELEASE.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 6902a445d..b18c90dd9 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -61,31 +61,38 @@ key changes in this release. Next update the contributors and render towncrier fragments by running: - $ tox -e changelog_release +```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: -.. code:: bash - - $ open docs/_build/html/changes/index.html +```sh +$ open docs/_build/html/changes/index.html +``` Or on Linux: -.. code:: bash +```sh +$ xdg-open docs/_build/html/changes/index.html +``` - $ xdg-open docs/_build/html/changes/index.html +If you need to go back and make any additional tweaks: -If you need to go back and make any additional tweaks, just -`git restore docs/changes` and re-run the tox command when ready for another -proofreading. Or if you just made a manual edit to the changelog RST, -you can simply re-render the docs: +```sh +$ git restore docs/changes +``` -.. code:: bash +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: - $ tox -e docs +```sh +$ tox -e docs +``` -If all looks good, remove the rendered towncrier fragments from +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 From d055892c589f09253aa7945176e8c6db95ae4707 Mon Sep 17 00:00:00 2001 From: Vytautas Liuolia Date: Sat, 12 Mar 2022 10:46:36 +0100 Subject: [PATCH 5/5] chore(tox.ini): remove some newlines and see if it wakes up Actions --- tox.ini | 2 -- 1 file changed, 2 deletions(-) diff --git a/tox.ini b/tox.ini index afeb21474..15fc36b74 100644 --- a/tox.ini +++ b/tox.ini @@ -409,8 +409,6 @@ deps = -r{toxinidir}/requirements/docs commands = {toxinidir}/tools/towncrier_draft.py --dry-run - - [testenv:changelog_release] deps = -r{toxinidir}/requirements/docs toml