Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc(changelog): reorganize towncrier #1621

Merged
merged 6 commits into from Mar 4, 2020

Conversation

csojinb
Copy link
Contributor

@csojinb csojinb commented Dec 15, 2019

Summary of Changes

Reorganize towncrier to match previous changelogs

Related Issues

N/A

Pull Request Checklist

This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

  • Added tests for changed code.
  • Prefixed code comments with GitHub nick and an appropriate prefix.
  • Coding style is consistent with the rest of the framework.
  • Updated documentation for changed code.
    • Added docstrings for any new classes, functions, or modules.
    • Updated docstrings for any modifications to existing code.
    • Added references to new classes, functions, or modules to the relevant RST file under docs/.
    • Updated all relevant supporting documentation files under docs/.
    • A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
    • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
  • Changes (and possible deprecations) have towncrier news fragments under docs/_newsfragments/. (Run towncrier --draft to ensure it renders correctly.)

If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

PR template inspired by the attrs project.

@csojinb csojinb force-pushed the reorganize-towncrier branch 2 times, most recently from 70dca33 to 4b60457 Compare December 15, 2019 23:56
docs/changes/3.0.0.rst Outdated Show resolved Hide resolved
docs/changes/3.0.0.rst Outdated Show resolved Hide resolved
Comment on lines 45 to 47
- The :attr:`~.RequestOptions.auto_parse_form_urlencoded` option is now
deprecated in favor of :class:`falcon.media.URLEncodedFormHandler`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, I can't comment on a file that has just been renamed, but it looks like this deprecation goes with the feature add for URLEncodedFormHandler. I was going to ask where it should go, since there is no longer a "deprecations" section. But, now I think the correct move is to combine these fragments.

Copy link
Member

@vytas7 vytas7 Dec 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, as discussed on Gitter, IMHO as long as deprecations are coming from the fact that we introduce newer and improved ways of doing things, it's fine to just mention them here.

It's still a bit of an open question what to do with pure deprecations that are not any impromevents per se, but we could maybe handle the case if/when it comes.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@csojinb
Copy link
Contributor Author

csojinb commented Dec 16, 2019

@vytas7 Draft PR for what we discussed about towncrier. This is on top of my other PR #1603, so only the last few commits are relevant. (Probably I should have just put the PR on my own fork. I forgot that I wouldn't be able to base it against my other branch.)

@csojinb
Copy link
Contributor Author

csojinb commented Dec 16, 2019

Looking again at the comments on #1603, I guess I should make two fragments for that one in this new setup.

@codecov
Copy link

codecov bot commented Dec 16, 2019

Codecov Report

Merging #1621 into master will increase coverage by 10.41%.
The diff coverage is n/a.

Impacted file tree graph

@@             Coverage Diff              @@
##           master     #1621       +/-   ##
============================================
+ Coverage   89.58%   100.00%   +10.41%     
============================================
  Files          43        47        +4     
  Lines        2860      3548      +688     
  Branches      425       550      +125     
============================================
+ Hits         2562      3548      +986     
+ Misses        280         0      -280     
+ Partials       18         0       -18     
Impacted Files Coverage Δ
falcon/http_error.py 100.00% <0.00%> (ø) ⬆️
falcon/testing/srmock.py 100.00% <0.00%> (ø) ⬆️
falcon/media/multipart.py 100.00% <0.00%> (ø) ⬆️
falcon/request_helpers.py 100.00% <0.00%> (ø) ⬆️
falcon/util/structures.py 100.00% <0.00%> (ø) ⬆️
falcon/asgi/structures.py 100.00% <0.00%> (ø)
falcon/asgi/app.py 100.00% <0.00%> (ø)
falcon/asgi/request.py 100.00% <0.00%> (ø)
falcon/asgi/stream.py 100.00% <0.00%> (ø)
falcon/util/misc.py 100.00% <0.00%> (+2.64%) ⬆️
... and 17 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e9b4b76...c40fd57. Read the comment docs.

pyproject.toml Outdated Show resolved Hide resolved
docs/changes/3.0.0.rst Outdated Show resolved Hide resolved
Misc
----

- Setup towncrier to make CHANGES reporting much easier. (use-towncrier)
Copy link
Member

@vytas7 vytas7 Dec 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a super big deal and a matter of taste, but would it be possible to disable these file names in the rendered output (eg (use-towncrier))?
Not sure if the information they convey is particularly useful for the reader. Or maybe they are useful in mentioning the issue number (?), but then we would need to make sure that all fragments start with an issue number.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, I misunderstood this and pushed a different change. If there is a way to suppress these file names, I don't know how. It's possible to suppress the prose content (which I did in one of the commits I just pushed, for the Misc section specifically), but that sounds like the opposite of what you want.

I do think that the intention is for this to be an issue number. Not sure if that should be the original issue or the PR that addresses it, but we might want to come up with some kind of consistent policy for that.

Copy link
Member

@vytas7 vytas7 Feb 1, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If Towncrier insists on those numbers, I'm thinking we could use the original issue number, and fall back to just the PR number in those rare cases anything is noteworthy in Towncrier, but does not have an issue number.

@kgriffs @jmvrbanac @nZac any preferences?

As discussed on Gitter, we could also set up a template to something like

`#{issue} <https://github.com/falconry/falcon/issues/{issue}>`_

to automatically link to the issue numbers. That would be neat actually. And GH converts issue links to PR links if you happen to provide one.

Copy link
Member

@vytas7 vytas7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good, I just had a couple of nitpicks as well as open questions for discussion 👍

In any case, let's just remove the rendered output from the final PR, and this is IMHO ready to at least be moved out from Draft.

@vytas7 vytas7 marked this pull request as ready for review December 29, 2019 19:00
Copy link
Member

@vytas7 vytas7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Just marking as "changes requested" so we don't forget to remove the throwaway demonstration of the rendered output)

@kgriffs
Copy link
Member

kgriffs commented Jan 17, 2020

Any chance we can land this patch over the next few days?

@kgriffs
Copy link
Member

kgriffs commented Jan 25, 2020

@csojinb what still needs to happen on this to get it over the finish line?

@csojinb
Copy link
Contributor Author

csojinb commented Feb 1, 2020

Hi sorry I haven't gotten back to this yet. Looking at it now

@csojinb
Copy link
Contributor Author

csojinb commented Feb 1, 2020

This is what the full output looks like as of 37aab61

Changelog for Falcon 3.0.0
==========================

Changes to Supported Platforms
------------------------------

- Python 3.8 is now fully supported.
- Python 3.6+ is only required when using the new ASGI interface. WSGI is still
  supported on Python 3.5+.
- Python 3.5 support is deprecated and may be removed in the next major release.
- Python 3.4 is no longer supported.
- The Falcon 2.x series was the last to support Python language version 2. As a
  result, support for CPython 2.7 and PyPy2.7 was removed in Falcon 3.0.

.. towncrier release notes start




Breaking Changes
----------------

- Exceptions are now handled by the registered handler for the most specific matching exception class, rather than in reverse order of registration. "Specificity" is determined by the method resolution order of the raised exception type. (See :meth:`~.App.add_error_handler` for more details.) (1603-smart-exception-handler-precedence)
- The deprecated ``stream_len`` property was removed from the ``Response`` class.
  Please use ``Response.set_stream()`` or ``Response.content_length`` instead. (stream_len)


New & Improved
--------------

- A new kwarg, ``cors_enable``, was added to the :class:`falcon.API` initializer.
  ``cors_enable`` can be used to enable a simple blanket CORS policy for all
  responses. (See also: :ref:`cors`.) (1194-cors)
- Falcon now supports all WebDAV methods (RFC 2518 and RFC 4918), such as COPY, LOCK, MKCOL, MOVE, PROPFIND, PROPPATCH and UNLOCK. (1426-webdav)
- The :meth:`~.Response.set_cookie` method now supports setting the
  `SameSite` cookie attribute. (1557-cookie-samesite)
- The :meth:`~.Response.add_link` method now supports setting the `crossorigin`
  link CORS settings attribute. (1574-add-link-crossorigin)
- :class:`falcon.media.URLEncodedFormHandler` was added for handling URL-encoded forms (of content
  type ``application/x-www-form-urlencoded``) as ``Request.media``. The :attr:`~.RequestOptions.auto_parse_form_urlencoded` option is now
  deprecated in favor of :class:`falcon.media.URLEncodedFormHandler`.
  (See also: :ref:`access_urlencoded_form`). (1580-auto-parse-form-urlencoded)
- The :meth:`~.Response.set_headers` method now accepts an instance of any dict-like
  object that implements an ``items()`` method. (1630-set-response)
- The ``falcon.API`` class was renamed to ``falcon.App``. The old ``API`` class
  remains available as an alias for backwards-compatibility, but it is now
  considered deprecated and will be removed in a future release. (api_class)
- When no route matches a request, the framework will now raise a
  specialized subclass of :class:`~.falcon.HTTPNotFound`
  (:class:`~.falcon.HTTPRouteNotFound`) so that
  a custom error handler can distinguish that specific case if desired. (default-404-responder-specialized-error)
- :meth:`falcon.testing.simulate_request` now accepts a
  `content_type` keyword argument. This provides a more convenient way to set
  this common header vs. the `headers` argument. (simulate-request-content-type)
- :meth:`~.Request.get_param_as_bool` now supports the use of ``'t'`` and ``'y'``
  values for ``True``, as well as ``'f'`` and ``'n'`` for ``False``. (support-additional-truthy-param-values)


Fixed
-----

- The ``uri.parse_query_string()`` utility function is now correctly parsing an
  empty string as ``{}``. (1600-parse-empty-query-string)
- Header-related methods of the ``falcon.Response`` class no longer coerce the
  passed header name to a string via ``str()``. (response-header-coercion)


Misc
----

- 1561-use-towncrier


Contributors to this Release
----------------------------

Many thanks to all of our talented and stylish contributors for this release!

- `screamingskulls <https://github.com/screamingskulls>`_

Per my comment here, I realized after I pushed this that I'd misunderstood @vytas7's request. So, I can change it back to including the prose content. Do you want me to go through and put issue numbers on all of the fragment names? If so, should it be the PR number or the original issue number?

@csojinb
Copy link
Contributor Author

csojinb commented Feb 1, 2020

Also, the build appears to be failing due to an inability to download a 3.8 archive? I don't know what to do about that

@vytas7
Copy link
Member

vytas7 commented Feb 1, 2020

Re the inability to download archives, that unfortunately happens from time to time on Travis.
I've now restarted the relevant job, let's see if we are any luckier this time 🤞

@kgriffs
Copy link
Member

kgriffs commented Feb 4, 2020

@csojinb did you see my reply on gitter?

@csojinb
Copy link
Contributor Author

csojinb commented Feb 4, 2020 via email

@kgriffs
Copy link
Member

kgriffs commented Feb 5, 2020

[copied from gitter]

I would suggest using the original issue number, if there is an issue, otherwise fall back to the PR #. But maybe it's too complicated?
@kgriffs @nZac @jmvrbanac any preferences?

@csojinb @vytas7 This sounds reasonable. Mainly I'd just like to ensure the fragment naming schema is consistent. We also need to talk about this in CONTRIBUTING and/or mention the desired format in the PR checklist template.

@csojinb
Copy link
Contributor Author

csojinb commented Feb 11, 2020

Dammit, I hit the wrong emoji and now it won’t let me unselect it. Yay I fixed it

@kgriffs I’m in favor of that suggestion. My personal computer has been having some troubles, so I’ve been a bit delayed in coming back to this, but I’ll try to get everything loaded up on my work machine and finish this up soon

@kgriffs
Copy link
Member

kgriffs commented Feb 13, 2020

Perhaps this belongs in a followup PR, but there is also the issue highlighted here:

#1655 (review)

I.e., it would be nice to be able to output links to the issue or PR at the end of the news fragment, but I haven't experimented enough with towncrier to know if it is possible to do this even when additional (hyphenated) descriptions are appended to the number. Outside of towncrier I suppose we could run a post-processing step to fix up things the way we want them.

Anyway, we should have some plan about how/if we want to address this, since it informs the naming scheme.

@kgriffs
Copy link
Member

kgriffs commented Feb 13, 2020

I’ve been a bit delayed

No worries; thanks for your help!

@kgriffs
Copy link
Member

kgriffs commented Feb 25, 2020

Any chance we could get this over the finish line by this weekend?

Copy link
Member

@vytas7 vytas7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@csojinb this looks great almost as-is IMHO.

If we accept the issue number-based naming scheme, i.e., (\d+).directory.rst, the only remaining items, in my understanding, are:

  • Rename all newsfragments to follow the decided naming scheme.
  • Update CONTRIBUTING.md explaining this scheme.
  • Check if .github/PULL_REQUEST_TEMPLATE.md needs an update.

@csojinb
Copy link
Contributor Author

csojinb commented Mar 3, 2020

I think I've managed to rename everything correctly. Here's the draft output again:

Breaking Changes
----------------

- The class :class:`~.falcon.http_error.NoRepresentation` was removed since
  all :class:`~.falcon.HTTPError` have optional representation. (`#777 <https://github.com/falconry/falcon/issues/777>`_)
- Header-related methods of the :class:`~falcon.Response` class no longer coerce the
  passed header name to a string via ``str()``. (`#1497 <https://github.com/falconry/falcon/issues/1497>`_)
- Exceptions are now handled by the registered handler for the most specific matching exception class, rather than in reverse order of registration. "Specificity" is determined by the method resolution order of the raised exception type. (See :meth:`~falcon.App.add_error_handler` for more details.) (`#1514 <https://github.com/falconry/falcon/issues/1514>`_)
- The deprecated ``stream_len`` property was removed from the :class:`~falcon.Response` class.
  Please use :meth:`~falcon.Response.set_stream()` or :attr:`~falcon.Response.content_length` instead. (`#1517 <https://github.com/falconry/falcon/issues/1517>`_)


New & Improved
--------------

- The error classes in ``falcon.errors`` were updated to have the ``title`` and
  ``description`` keyword arguments and to correctly handle headers passed as
  list of tuples (`#777 <https://github.com/falconry/falcon/issues/777>`_)
- :class:`~falcon.media.MultipartFormHandler` was added for handling multipart forms (of content
  type ``multipart/form-data``) as ``Request.media``. (`#953 <https://github.com/falconry/falcon/issues/953>`_)
- A new kwarg, ``cors_enable``, was added to the :class:`falcon.App` initializer.
  ``cors_enable`` can be used to enable a simple blanket CORS policy for all
  responses. (See also: :ref:`cors`.) (`#1194 <https://github.com/falconry/falcon/issues/1194>`_)
- The :meth:`~falcon.Response.add_link` method now supports setting the `crossorigin`
  link CORS settings attribute. (`#1410 <https://github.com/falconry/falcon/issues/1410>`_)
- Falcon now supports all WebDAV methods (RFC 2518 and RFC 4918), such as COPY, LOCK, MKCOL, MOVE, PROPFIND, PROPPATCH and UNLOCK. (`#1426 <https://github.com/falconry/falcon/issues/1426>`_)
- The :meth:`~falcon.Response.set_headers` method now accepts an instance of any dict-like
  object that implements an ``items()`` method. (`#1546 <https://github.com/falconry/falcon/issues/1546>`_)
- Change :class:`falcon.routing.CompiledRouter` to compile the routes
  only when the first request is routed. This can be changed by
  passing ``compile=True`` to :meth:`falcon.routing.CompiledRouter.add_route`. (`#1550 <https://github.com/falconry/falcon/issues/1550>`_)
- The :meth:`~falcon.Response.set_cookie` method now supports setting the
  `SameSite` cookie attribute. (`#1556 <https://github.com/falconry/falcon/issues/1556>`_)
- The ``falcon.API`` class was renamed to :class:`falcon.App`. The old ``API`` class
  remains available as an alias for backwards-compatibility, but it is now
  considered deprecated and will be removed in a future release. (`#1579 <https://github.com/falconry/falcon/issues/1579>`_)
- :class:`~falcon.media.URLEncodedFormHandler` was added for handling URL-encoded forms (of content
  type ``application/x-www-form-urlencoded``) as ``Request.media``. The :attr:`~.RequestOptions.auto_parse_form_urlencoded` option is now
  deprecated in favor of :class:`~falcon.media.URLEncodedFormHandler`.
  (See also: :ref:`access_urlencoded_form`). (`#1580 <https://github.com/falconry/falcon/issues/1580>`_)
- :meth:`~falcon.Request.get_param_as_bool` now supports the use of ``'t'`` and ``'y'``
  values for ``True``, as well as ``'f'`` and ``'n'`` for ``False``. (`#1606 <https://github.com/falconry/falcon/issues/1606>`_)
- :meth:`falcon.testing.simulate_request()` now accepts a
  `content_type` keyword argument. This provides a more convenient way to set
  this common header vs. the `headers` argument. (`#1646 <https://github.com/falconry/falcon/issues/1646>`_)
- When no route matches a request, the framework will now raise a
  specialized subclass of :class:`~.falcon.HTTPNotFound`
  (:class:`~.falcon.HTTPRouteNotFound`) so that
  a custom error handler can distinguish that specific case if desired. (`#1647 <https://github.com/falconry/falcon/issues/1647>`_)


Fixed
-----

- The :func:`~falcon.uri.parse_query_string()` utility function is now correctly parsing an
  empty string as ``{}``. (`#1600 <https://github.com/falconry/falcon/issues/1600>`_)
- :attr:`falcon.Request.forwarded_host` now contains the port when proxy headers
  are not set, to make it possible to correctly reconstruct the URL when the
  application is not behind a proxy. (`#1678 <https://github.com/falconry/falcon/issues/1678>`_)


Misc
----

- Deprecate the use of positional arguments for the optional kw args of
  the HTTPError subclasses (`#777 <https://github.com/falconry/falcon/issues/777>`_)
- Setup towncrier to make CHANGES reporting much easier. (`#1561 <https://github.com/falconry/falcon/issues/1561>`_)
- Fix test errors on Windows (`#1656 <https://github.com/falconry/falcon/issues/1656>`_)

@csojinb
Copy link
Contributor Author

csojinb commented Mar 3, 2020

I'm testing out the docs now and making sure that the links all work properly in the GH markdown files, then I'll clean up the git history and I think this should be g2g

- Rename categories and extensions to match previous changelogs
- Reorganize existing fragments into categories
- Combine fragments for same issue that previously fell into different categories
- Remove duplicate platform support change notes
- Document newsfragment naming rules
- Add issue format template, with github issue links
News fragments now named for either the originating github issue, if
there is one, or the PR issue number if there is not
- fix some cross references that were broken by subsequent commits
and missed because the news fragments don't get built into the docs
- add cross references to several news fragments
@csojinb csojinb changed the title Reorganize towncrier doc(changelog): reorganize towncrier Mar 3, 2020
@csojinb
Copy link
Contributor Author

csojinb commented Mar 3, 2020

  • Rename all newsfragments to follow the decided naming scheme.
  • Update CONTRIBUTING.md explaining this scheme.
  • Check if .github/PULL_REQUEST_TEMPLATE.md needs an update.

@csojinb
Copy link
Contributor Author

csojinb commented Mar 3, 2020

@vytas7 @kgriffs I think this should be ready now

vytas7
vytas7 previously approved these changes Mar 3, 2020
Copy link
Member

@vytas7 vytas7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking great now! 👍 🎉

Copy link
Member

@vytas7 vytas7 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've tried actually rendering the docs and they look great. 👍
I've just taken the liberty of mving one issue number that look misplaced to me.

@csojinb
Copy link
Contributor Author

csojinb commented Mar 3, 2020

@vytas7 thanks for fixing the issue number! is there anything else that you need from me here, or can I just leave it to y'all to get merged?

@vytas7
Copy link
Member

vytas7 commented Mar 3, 2020

The only thing I'd like to get before merging is @kgriffs seal of approval 🤣

Great job cleaning this up @csojinb 🎉 ! This towncrier stuff was a royal mess before.

@vytas7 vytas7 requested review from kgriffs and nZac March 3, 2020 18:30
Copy link
Member

@kgriffs kgriffs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for cleaning this up!

You're Awesome

Approved

@kgriffs kgriffs merged commit 3bbeea3 into falconry:master Mar 4, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants