tracking backwards-incompatible changes

[belm0]

Subscribe to this issue for notices of backward-incompatible changes.

Occasional API changes in trio-util should be expected. The current policy is that such changes may happen within minor version increments (middle number of the version). Bugfix increments (last number) will never have intentional breaking changes. Therefore:

1. if your application or package build/test environment depends on trio-util, it's best practice to pin the entire version (e.g. via pip-compile tool)
2. if your package has a trio-util requirement, then... it's tricky. Ideally you'd specify only a minimum version, and make the package work with old and new trio-util versions by various means (so that apps or dependees using your package are free to choose a trio-util version).

Regarding packages depending on trio-util, roughly these levels of care about compatibility are possible:

• best effort (0 dependee packages, current situation) - occasional breaking changes, no deprecation cycle
• deprecating changes (> 0 dependee packages) - occasional breaking changes, but backwards compatibility will be provides for a few minor releases. (It's hard to do for some changes, like transitioning a function between sync and async.)
• major version only (significant dependee packages) - breaking changes are made with major version increments only, so dependee packages can safely specify a version like ~= 2.1 (i.e. any major version 2, with minor version >= 1).

As the number of packages depending on trio-util increases, I'll try to adjust the priority to suit.

[belm0]

breaking changes in upcoming release trio-util 0.5.0:

• compose_values() context manager was changed from async to synchronous
• RepeatedEvent replaces both UnqueuedRepeatedEvent and MailboxRepeatedEvent