2.0 backwards compatibility breaks

[lemon24]

This is to track all the backwards compatibility breaks we want to do in 2.0.

Things that require deprecation warnings pre-2.0:

• (maybe) rename remove_feed to delete_feed, for consistency with delete_feed_metadata; copy guidance: one, two, three
  • remove backwards compatibility with the pre-1.18 method
• (maybe) rename the .url attribute of EntryError and MetadataError to .feed_url, for consistency with the Entry objects; Exception messages are inconsistent #173 (comment)
  • remove backwards compatibility with the pre-1.18 method
• (maybe) rename the mark_as_... methods to mark_entry_as_...
  • remove backwards compatibility with the pre-1.18 methods
• (done in 1.18) rename iter_feed_metadata to get_all_feed_metadata; I have to go through all the entries to find out how many there are #185 (comment)
  • remove backwards compatibility with the pre-1.18 methods
• get rid of update_feeds/_iter(new_only=...); I can't get the new feed counts #217
  • deprecate
  • remove
• rename UpdatedFeed.updated to .modified; [Question] Public API for recently fetched entries, or entries added/modified since date? #241 (comment)
  • remove backwards compatibility property

Things that do not require / can't have deprecation warnings pre-2.0:

• make update_feeds/_iter() arguments kw-only; I can't get the new feed counts #217
• use timezone-aware datetimes; Use timezone-aware datetimes everywhere in the public API #233
• do not allow file:// feeds by default; Handle non-http feeds gracefully in the web app #155 (comment)
• stop supporting non-PRAGMA-user_version migrations; Use PRAGMA user_version instead of a version table #210; the upgrade path from reader<=1.13 to reader>=2 will require upgrading to reader>=1.14,<2 first
• drop all 1.x migrations; the upgrade path from reader 1.x to reader 2 will require upgrading to reader 1.latest first
• allow make_reader() to raise any ReaderError, not just StorageError; was needed for Minimal API to enable/disable built-in plugins #229
• (done in 1.18) remove old-style config support from the mark_as_read plugin
• make Entry.updated Optional[datetime] instead of datetime (without changing any of the logic, see below)

Postponed:

• (done in 2.5) make Entry.updated Optional[datetime] instead of datetime; requires migration; Entries change without updated being bumped #179 (comment)
  • or, we can just change the declared type, and do the change at some later point
• (done in 2.5) validate the feed URL in add_feed() and change_feed_url() by default; Handle non-http feeds gracefully in the web app #155 (comment)
• (maybe, YAGNI) do not use None arguments to mean something else aside from "no value"/"default"; CLI options must be passed all the time #177 (comment)
• (maybe, YAGNI) make get_feed_tags return TagInfo objects; I have to go through all the entries to find out how many there are #185 (comment); likely only needed if we end up having a get_feed_tag_info method
• (done in 2.3) make the default behavior of the entry_dedupe plugin be delete; Allow entry_dedupe to delete the old entries #140 (comment)

[lemon24]

The changes list for each API thing is getting quite big now, maybe hide it for old versions with https://pypi.org/project/sphinxcontrib-log-cabinet/

Update: Done.

[lemon24]

Regarding "make Entry.updated Optional[datetime] instead of datetime (without changing any of the logic, see below)" / #179 (comment):

It'd be nice to have a different attribute/property with the same semantics updated has now, that is updated or first_updated:updated_??? always gives you a date, which most of the time is updated (unless it's missing); updated_??? tries to align with human expectations, rather than be "correct".

The name should convey updated_<best guess>, or updated_<guaranteed to be non-null>. Some candidates:

• updated_best_guess
• updated_best_effort
• updated_best_value
• updated_collated
• updated_assumed
• updated_composite
• updated_computed
• updated_required
• updated_nonoptional
• updated_not_none (examples: one, two) ←