Hey @pganssle — thanks for this!

I've posted to the list about whether we can squeeze this in, if we can't get full review before Thursday.

Are the TODOs in your first comment still up to date?

@carltongibson I have updated the TODOs accordingly. I think that there are two remaining questions here:

1. Currently, make_aware will ignore is_dst for non-pytz zones, because the semantics of fold and is_dst is not a perfect mapping. Since fold is set on the value parameter and has no default, there's no way to detect if someone has deliberately set fold and is_dst, and it's not clear which should take precedence.

   I could reasonably migrate the logic from pytz-deprecation-shim here, which is that is_dst is ignored when not specified (value's fold is used instead), and if explicitly specified, normal pytz logic applies (we'd need to swap out the AmbiguousTimeError and NonExistentTimeError for another exception type in the None case, obviously). In the end I think is_dst should be deprecated or removed or something in whatever version built-in zoneinfo support rolls out in, since the semantics aren't quite right.

2. A related concern is what to do about this date truncation logic. This is similar to the other issue in that it comes down to how is_dst should work. The difference is that with make_aware, you are passing a datetime directly, and can thus set the fold. In this case the datetime is created for you behind the scenes, and you only have the is_dst lever. We can leave this as-is and have people "fix it in post" if they opt-in, or we can add the is_dst resolution logic directly into the TruncBase.convert_value code, or we can add the is_dst support to make_aware and the truncation logic will be inherited automatically.

That stuff is the only possible backwards-compatibility concern in this PR, since to the extent that it's possible to use make_aware and the truncation logic with non-pytz zones today, is_dst is already ignored. Making it sometimes raise exceptions could be a backwards incompatible change (though if we're taking something that was broken and unusable and making it usable maybe that's not a really incompatible change). One option to get around this would be to disable the is_dst=None behavior for non-pytz zones and add a new singleton like django.utils.timezone.ERROR_UNLESS_UNAMBIGUOUS (or accept the string 'error') that triggers the is_dst=None behavior even in non-pytz zones.

In any case, I would say that even without any changes to the is_dst logic, this PR is a win for DJango users, and we shouldn't let the perfect be the enemy of the good. I think any wonky DST logic that would come about from the lack of is_dst support for non-pytz zones could be fixed reasonably easily by end users anyway.

It seems ok to me. I added only a small comment.

@adamchainz I've made some minor updates to the i18n documentation, but a lot of the references to pytz are very specific to pytz, and might require a more significant overhaul to show both ways of doing things.

I'd also say that this advice, while not so pytz-specific, is a bit of a problematic recommendation, as the tz project is pretty clear that the database keys that pytz.common_timezones and zoneinfo.available_timezones() expose are not really intended to be user-facing, but "how to create a timezone-picker" is a much more difficult and complicated topic to address.

I think for now it's probably best to just acknowledge that non-pytz zones are supported (and intended to be supported), and decide later on whether it's worth overhauling the docs to show both pytz and zoneinfo support side-by-side.

🎉

Thanks so much for your help with this everyone. This was a great first experience contributing to Django ❤️