API changes in version 2.0?

[tobixen]

Creating a new issue to keep track of changes to be considered for an upcoming 1.0-release. This top entry will be edited to reflect all significant changes planned.

Backward compatibility plan

I would like users to be able to upgrade to 1.0 without changing anything, if possible (though, hacks to support usage patterns from 0.5 and earlier may be dropped in 1.0). When version 2.0 comes, all hacks to support backward-compatibility with 1.x will be removed. My suggestion is that the proper usage of 1.0 is to start with something this:

from caldav import CalDAVClient
client = CalDAVClient(**connection_arguments)
principal = client.get_principal()

and then everything should be doable starting with the objects client or principal. In version 2.0, caldav/caldav/__init__.py will be trimmed to only reveal the CalDAVClient. All operations starting with CalDAVClient will results in objects/classes supporting the 1.0-API. For the classes where the API is changed, we'll create a new class with a class name ending with "NG" (new generation), inheritate the old class, and do the needed changes. In version 2.0 we'll refactor and remove the NG-cruft.

In 1.0, DAVClient will be a class for backward-compatibility with version 0.x. In version 2.0 we should consider to split out DAV-support to a separate davclient-module.

API Changes

• some_obj.instance is deprecated, new methods some_obj.icalendar_instance and some_obj.vobject_instance (as well as some_obj.icalendar_component)
• Drop python2 support #228
• Think through properties vs methods, and be more consistent. Use verbs for all methods? Like principal.get_calendar(), client.get_principal(), etc. Properties should probably never cause any communication towards the calendar server. Access of properties should probably never cause side effects (the current instance and data properties may have side effects).

[tobixen]

SEMVER states ...

If your software is being used in production, it should probably already be 1.0.0.
If you have a stable API on which users have come to depend, you should be 1.0.0.
If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.

All three points apply, hence a 1.0-release is way overdue.

New tentative road map:

• There won't be any 0.12. There will be a 1.0.0.
• 1.0.0 will be fully backward-compatible with 0.11.
• Already in 0.11, I've marked up some stuff as DEPRECATED. This stuff will be abandoned as of a future 2.0.0-release (or perhaps 3.0.0 for important things like date_search )
• We will gradually think of what is sub-optimal with the API while working on the 1.x-series and perhaps make a new and better API available prior to a future 2.0.0-release.
• I will think out (or check out what others are using) some framework to warn when library users are using some deprecated API.

@cyrilrbt do you have any opinions?

[cyrilrbt]

It's always been my intention to align with semver so let's go for it!
This is a good idea, and it will be useful for future releases, go for it :)