docs: git commit message policy changes, warn about async issues

Author: tobixen

AI-POLICY.md

@@ -4,8 +4,8 @@
 
 The most important rule: be honest and inform about it!
 
-Keep a log of the prompts used - prompts may be included in the
-git commits.
+Keep a log of the prompts used - prompts should be included in the
+git commits
 
 Tools should be used for improving the quality of the project, not for
 rapidly adding new features.

CHANGELOG.md

@@ -27,12 +27,13 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
   * raised `KeyError` when the server did not include the `supported-calendar-component-set` property in its response.  RFC 4791 section 5.2.3 states this property is optional and that its absence means all component types are accepted; the method now returns the RFC default `["VEVENT", "VTODO", "VJOURNAL"]` in that case, trimmed by any known server limitations from the compatibility hints (e.g. if `save-load.todo` is `unsupported`, `VTODO` is excluded).  Fixes https://github.com/python-caldav/caldav/issues/653
   * async path returned an unawaited coroutine instead of the actual result.
 * `accept_invite()` (and `decline_invite()`, `tentatively_accept_invite()`) now fall back to the client username as the attendee email address when the server does not expose the `calendar-user-address-set` property (RFC6638 §2.4.1).  A `NotFoundError` with a descriptive message is raised when the username is also not an email address.  Fixes https://github.com/python-caldav/caldav/issues/399
+* `get_object_by_uid()` now passes `include_completed=True` so completed todos are found by UID lookup (previously they were silently missed).  `get_todo_by_uid()` now uses `comp_class=Todo` instead of a raw VTODO `CompFilter`, aligning it with the rest of the search API.  Closes https://github.com/python-caldav/caldav/issues/586
+* Sync `_put()` now updates `self.url` from the `Location` header on a 302 redirect, mirroring the existing async behaviour.
 
 ### Housekeeping
 
 * Added `funding.json` (https://fundingjson.org/) at the repository root.  Closes https://github.com/python-caldav/caldav/issues/608
 * Code quality: reduced ruff ignore list (https://github.com/python-caldav/caldav/issues/634) — removed unused imports (`copy`, `lxml.etree`, `CalendarSet`, `cdav/dav` re-exports, `Optional`, `timezone`, `Event`/`Todo` type stubs), replaced bare `except:` clauses with specific exception types (`KeyError`, `AttributeError`, `Exception` where broad catching is intentional), and removed unused local variables.
-* Sync `_put()` now updates `self.url` from the `Location` header on a 302 redirect, mirroring the existing async behaviour.
 
 ### Test framework, compatibility hints, documentation, examples
 

CONTRIBUTING.md

@@ -15,7 +15,7 @@ The types used should (as for now) be one of:
 * "refactor" - a code change in the codebase that is neither a bugfix or a feature, but makes the code more readable, shorter, better or more maintainable.
 * "test" - fixes, additions or improvements that only affects the test code or the test framework.  The commit may include documentation.
 * "docs" - changes that *only* is done to the documentation, documentation framework - this includes minor typo fixes as well as new documentation, and it includes both the user documentation under `docs/source`, other documentation files (including CHANGELOG) as well as inline comments and docstrings in the code itself.
-* "other" - if nothing of the above fits
+* "chore" - if nothing of the above fits
 
 The `compatibility_hints.py` has been moved from the test directory to the codebase not so very long ago.  Some special rules here:
 

docs/source/async.rst

@@ -9,6 +9,11 @@ The caldav library provides an async-first API for use with Python's
 * Integrate with async web frameworks (FastAPI, aiohttp, etc.)
 * Build responsive applications that don't block on I/O
 
+Caveat
+======
+
+A "Sans-IO" design pattern was followed, in a hope that it would make it possible to have one library serve both the async and sync use case through relatively similar APIs without duplicating too much code.  In retro-perspective I'm not sure this was the best idea for the CalDAV library.  Be aware that there are still exists code paths that works well with the sync code but will blow up if you try using it with the async code.
+
 Quick Start
 ===========