|
| 1 | +# Python CalDAV Client Library - Roadmap |
| 2 | + |
| 3 | +Hopefully I will have some time to work on the Python CalDAV library in the upcoming months. I'm now trying to make this "super issue" to prioritize the outstanding work, throw some estimates on the work tasks and break down the projects. |
| 4 | + |
| 5 | +## Summary first |
| 6 | + |
| 7 | +Estimated outstanding work: |
| 8 | + |
| 9 | +* Close outstanding pull requests - 12h |
| 10 | +* Outstanding issues slated for v1.5 - 22h |
| 11 | +* Documentation work - 18h |
| 12 | +* Server checker and server compatibility hints project - 28h |
| 13 | +* Outstanding issues slated for v2.0 - 23h |
| 14 | +* New application interface - 20h |
| 15 | +* New interface + asyncio projects - 50h |
| 16 | +* Outstanding issues slated for v3.0 - 12h |
| 17 | +* Maintain and expand the test server list - 8h |
| 18 | +* JMAP project - 40h |
| 19 | +* Other outstanding issues - 83h |
| 20 | + |
| 21 | +I do believe I can manage to contribute somewhere between 5 and 30 hours per month to the caldav project over the upcoming year. That's between 60 and 360 hours. In the very best scenario it will be possible to get everything above done. Most likely something has to go out, most likely many outstanding issues slated for v1.5 will be procrastinated, same with the JMAP project and quite some of the v2.0-issues. |
| 22 | + |
| 23 | +This being open source, I'm not doing everything alone, there is a steady stream of contributions from other contributors ticking in - but most of those contributions are related to new issues - unknown bugs and features I haven't think about. Generally community contributions improve the overall quality of the project, but contributes negatively to the roadmap schedule. Most reported issues comes iwthout pull-requests, even when there are pull-requests it takes some time to do QA on the contributions, add missing test code, documentation and changelog entries. |
| 24 | + |
| 25 | +## The higher goals |
| 26 | + |
| 27 | +For all work that is done, it's important to consider if it's bringing the project in the right direction or not, defined as such: |
| 28 | + |
| 29 | +* The library should offer high-level easy-to-use methods for doing interaction with CalDAV servers (but it should also offer lower-level methods). |
| 30 | +* The library should just work - with a bare minimum of configuration (but it should also be possible to do advanced configuration). |
| 31 | +* The high-level methods should be accessible for people who know nothing about the CalDAV standard nor the iCalendar standard (while the low-level methods should give power-users unlimited possibilities). |
| 32 | +* The CalDAV standard is currently the only widely adopted standard for calendar access, though it's not a very good standard - when newer standards are evolving, the scope for the library may change. |
| 33 | +* The library should work consistently towards different server implementations |
| 34 | + |
| 35 | +## Outstanding pull requests |
| 36 | + |
| 37 | +It's important to get done with some pull requests - many of them is work that I've started on and got partly or mostly done, but I never had time to complete it. Some of it may be considered "low hanging fruit" as most or parts of the work is already done. |
| 38 | + |
| 39 | +* [Support for alarms](https://github.com/python-caldav/caldav/issues/132) - several users have requested better support for alarms. Work has been done to make high-level interface for creating events with alarms and searching for events based on alarms, but the functional tests were procrastinated as the test servers didn't support alarms. Functionality for "find the next upcoming alarms" is also missing. Estimate: 4h |
| 40 | +* [Relationship validation](https://github.com/python-caldav/caldav/pull/336) - While the RFCs says nothing about it, I believe it's good practice to have a two-way linking in the `RELATED-TO`-property (if a "child" is pointing to a "parent", the "parent" should point back to the child). The pull request should allow going through all events in the calendar and verify that no such links are missing, as well as fix missing links. Estimate: 3h |
| 41 | +* [Repairing the Readthedocs sync](https://github.com/python-caldav/caldav/pull/453) - https://caldav.readthedocs.io/en/latest/ is stuck on 1.3.6, while the latest release is 1.4, I need to figure out what's the problem here, fix it and verify that things are working. Estimate: 2h. |
| 42 | +* [Compatibility workaround: Accept XML content from calendar server even if it's marked up with content-type text/plain](https://github.com/python-caldav/caldav/pull/465). Estimate: 1h |
| 43 | +* [Server checker](https://github.com/python-caldav/caldav/pull/451) - this is part of the "server compatibility hints"-project, more information below. |
| 44 | +* [Code cleanup](https://github.com/python-caldav/caldav/pull/437) - Estimate: 2h |
| 45 | + |
| 46 | +## Documentation work |
| 47 | + |
| 48 | +The documentation is not much good nor intuitive for new users. People are encuraged to check some example code inside the repository, but this example code is not tested regularly. The code should be embedded in the documentation and executed by the test suite. |
| 49 | + |
| 50 | +* Make a way to embed code in the documentation and have it executed by functional tests. Estimate: 2h |
| 51 | +* Move the existing example code into documentation and improve it. Estimate: 3h |
| 52 | +* Look through the documentation, reorganize it, write more and better doc. Estimate: 6h |
| 53 | +* Loko through all the outstanding documentation issues. Estimate: 3h |
| 54 | +* Update the documentation again, after fixing all other issues mentioned here. Estimate: 4h |
| 55 | + |
| 56 | +### Related issues and pull requests |
| 57 | + |
| 58 | +* https://github.com/python-caldav/caldav/issues/100 |
| 59 | +* https://github.com/python-caldav/caldav/issues/119 |
| 60 | +* https://github.com/python-caldav/caldav/issues/120 |
| 61 | +* https://github.com/python-caldav/caldav/issues/239 |
| 62 | +* https://github.com/python-caldav/caldav/issues/253 |
| 63 | +* https://github.com/python-caldav/caldav/issues/256 |
| 64 | +* https://github.com/python-caldav/caldav/issues/269 |
| 65 | +* https://github.com/python-caldav/caldav/issues/311 |
| 66 | + |
| 67 | +## Project: Server compatibility hints |
| 68 | + |
| 69 | +There is a jungle of calendar servers out there, the RFCs are sometimes ambiguous, and quite a lot in the RFCs is optional to implement. Ideally, a python program using the caldav library should behave the same even if the calendar servers behaves differently - for instance, if the calendar server does not support search, the search operation may work by downloading the whole calendar and do a client-side search. A side-project (and requisite) here is a server-checker script that may run various tests towards a calendar server to check for compatibility issues. The server checker script is partially done, but got derailed due to lack of time. |
| 70 | + |
| 71 | +### Subtasks |
| 72 | + |
| 73 | +* The current "quick list" is a mess and needs to be cleanded up and reorganized. After doing that, the functional tests and the server checker script must be rewritten to comply with the new list. Estimate: 5h |
| 74 | +* The server checker script needs to be refactored - currently it's only possible to run all checks or nothing, it should be possible to check one quirk without running the full test suite. This is slightly non-trivial as the current script sometimes needs data from one quirk test run before it can run another quirk test. Estimate: 6h |
| 75 | +* The server configuration for caldav should be improved |
| 76 | + * In "auto-mode" (default) the client should do a quick effort on figuring out compatibility quirks, guessing the correct URL, etc. Estimate: 2h |
| 77 | + * In "probe-mode", the client should do extensive probing to figure out of things. Estimate: 2h |
| 78 | + * In "manual" mode, the client should assume the configuration it gets is correct. |
| 79 | + * It should accept a parameter telling it what kind of server is in use ... i.e. `server_impementation=nextcloud` and it would know that all nextcloud-quirks should be applied. It's complicated as version numbers also has to be taken into consideration. Alternatively, it should be possible to pass a complete quirk-list. Estimate: 3h |
| 80 | + * It should be possible to configure some few other things. Estimate: 1h |
| 81 | + * Is it allowed to download the full calendar i.e. to do a client text search? |
| 82 | + * If an operation is known to fail due to the quirk-list, should the server raise an error, or should it try anyway? |
| 83 | + * Should we do work-arounds to ensure consistency across different calendar servers? (this may break consistency towards elder versions of the library) |
| 84 | + * ... probably more options as well .. |
| 85 | + * Now that we have a quirk-list, it should be utilized: |
| 86 | + * Try to identify all the points in the code where we should do differently dependent on the quirk list and configuration. Estimate: 3h |
| 87 | + * Try to mitigate as many of the quirks as possible, and raise errors when the server does not support the operation. Estimate: 6h |
| 88 | + |
| 89 | +### Related issues and pull requests |
| 90 | + |
| 91 | +* https://github.com/python-caldav/caldav/pull/451 |
| 92 | +* https://github.com/python-caldav/caldav/issues/463 |
| 93 | +* https://github.com/python-caldav/caldav/issues/402 |
| 94 | +* https://github.com/python-caldav/caldav/issues/102 |
| 95 | +* https://github.com/python-caldav/caldav/issues/183 |
| 96 | +* https://github.com/python-caldav/caldav/issues/203 |
| 97 | +* https://github.com/python-caldav/caldav/issues/351 |
| 98 | +* https://github.com/python-caldav/caldav/issues/401 |
| 99 | + |
| 100 | +## Project: New interface |
| 101 | + |
| 102 | +The current interface has grown organically and without much thought. Method names are inconsistent, the workflow is inconsistent, in some places a property is in use while other places a method is in use. The library was also made back when "Python 3k" was a long-in-the-future project, and while async operation meant one would have to understand the twisted "Twisted" framework. I think it may be useful to think through things and make a new application interface from scratch. I deem backward compatibility high, so the new and old application interface will live side by side (but eventually with deprecation warnings) for a while. This involves quite a lot of thinking and documentation, some refactoring of current code, but should not involve duplicating code nor "writing things from scratch". |
| 103 | + |
| 104 | +This should be done a bit in lockstep with the asyncio project. One idea may be to create the new interface for async usage and leave the old interface for sync usage. The estimate is set low because much of the actual work is done in the asyncio project. |
| 105 | + |
| 106 | +Estimate: 10h |
| 107 | + |
| 108 | +### Related issues and pull requests |
| 109 | + |
| 110 | +* https://github.com/python-caldav/caldav/issues/92 |
| 111 | +* https://github.com/python-caldav/caldav/issues/128 |
| 112 | +* https://github.com/python-caldav/caldav/issues/180 |
| 113 | +* https://github.com/python-caldav/caldav/issues/232 |
| 114 | +* https://github.com/python-caldav/caldav/issues/240 |
| 115 | + |
| 116 | +## Project: asyncio |
| 117 | + |
| 118 | +Modern Python applications should work asynchronously. |
| 119 | + |
| 120 | +I haven't thought much about how to achieve this - but I give a very rough estimate that it will take me one working week to figure it out and implement it. |
| 121 | + |
| 122 | +Estimate: 40h |
| 123 | + |
| 124 | +### Related issues and pull requests |
| 125 | + |
| 126 | +* https://github.com/python-caldav/caldav/issues/342 |
| 127 | +* https://github.com/python-caldav/caldav/pull/455 |
| 128 | +* https://github.com/python-caldav/caldav/issues/457 |
| 129 | + |
| 130 | +## Project: JMAP |
| 131 | + |
| 132 | +JMAP is a new email protocol intended to replace IMAP - at FOSSDEM 2025 it appeared that both server developers and client developers found it superior compared to IMAP. The JMAP protocol also supports the exchange of calendaring data. |
| 133 | + |
| 134 | +I think it would be nice with a library where the high-level methods would work seamlessly for the end user no matter if the CalDAV protocol or the JMAP protocol is used. The first step of this project would be to investigate if this is at all possible - if not, we may need to make changes to the high-level API. |
| 135 | + |
| 136 | +Supporting JMAP may not be intuitive considering the naming of the library, but it may be important for future-proofing the library. |
| 137 | + |
| 138 | +It's prerequisite to find calendar servers supporting JMAP for testing. |
| 139 | + |
| 140 | +### Related issues and pull requests |
| 141 | + |
| 142 | +* https://github.com/python-caldav/caldav/issues/424 |
| 143 | + |
| 144 | +Estimate: 40h |
| 145 | + |
| 146 | +## Increase the list of test servers |
| 147 | + |
| 148 | +This involves signing up at different cloud providers, begging for test accounts from people who are running calendar servers, setting up my own self-hosted servers, etc. Trying to keep an overview at https://github.com/python-caldav/caldav/issues/45 and in my own private config file. |
| 149 | + |
| 150 | +Estimate: 8h |
| 151 | + |
| 152 | +## Other outstanding issues |
| 153 | + |
| 154 | +I try to prioritize the issues in the github tracker by using the "milestone" concept. The milestones correspond to some future release. It's a very optimistic estimate on what release the issue will be fixed in, so in the end I freqeuently push the milestone target. |
| 155 | + |
| 156 | +### 1.x milestone |
| 157 | + |
| 158 | + |
| 159 | +* https://github.com/python-caldav/caldav/issues/458 - case sensitivity in http headers - Estimate: 1h |
| 160 | +* https://github.com/python-caldav/caldav/issues/262 - look once more into setup.py vs pyproject.toml etc - Estimate: 2h |
| 161 | +* https://github.com/python-caldav/caldav/issues/237 - search for journals - Estimate: 1h |
| 162 | +* https://github.com/python-caldav/caldav/issues/115 - multiget - Estimate: 1h |
| 163 | +* https://github.com/python-caldav/caldav/issues/120 - RFC6638 support - Estimate: 4h |
| 164 | +https://github.com/python-caldav/caldav/issues/163 - Exception thrown in tentatively_accept_invite - Estimate: 2h |
| 165 | +* https://github.com/python-caldav/caldav/issues/151 - Some Apple problems - Estimate: 1h |
| 166 | +* https://github.com/python-caldav/caldav/issues/206 - trouble with .netrc - Estimate: 1h |
| 167 | +* https://github.com/python-caldav/caldav/issues/309 - trouble with GMX - Estimate: 2h |
| 168 | +* https://github.com/python-caldav/caldav/issues/330 - another path handling problem - Estimate: 1h |
| 169 | +* https://github.com/python-caldav/caldav/issues/356 - a missing method - Estimate: 2h |
| 170 | +* https://github.com/python-caldav/caldav/issues/379 - Edit a single occurence of a recurrent event - Estimate: 2h |
| 171 | +* https://github.com/python-caldav/caldav/issues/476 - Verify that there are no internal dependencies on vobject - Estimate: 1h |
| 172 | +* https://github.com/python-caldav/caldav/issues/478 - problem with Fastmail - Estimate: 1h |
| 173 | + |
| 174 | +### 2.0 milestone |
| 175 | + |
| 176 | +* https://github.com/python-caldav/caldav/issues/462 - better support for proxying, better tests, better doc - Estimate: 3h |
| 177 | +* https://github.com/python-caldav/caldav/issues/93 - increase test coverage, again - Estimate: 4h |
| 178 | +* https://github.com/python-caldav/caldav/issues/99 - documentation and refactoring of test runs - Estimate: 1h |
| 179 | +* https://github.com/python-caldav/caldav/issues/96 - refactoring - Estimate: 2h |
| 180 | +* https://github.com/python-caldav/caldav/issues/131 - cross-principal calendar search - Estimate: 4h |
| 181 | +* https://github.com/python-caldav/caldav/issues/334 - some missing test code - Estimate: 1h |
| 182 | +* https://github.com/python-caldav/caldav/issues/340 - google compatibility - Estimate: 2h |
| 183 | +* https://github.com/python-caldav/caldav/issues/380 - intermedient test problem - Estimate: 1h |
| 184 | +* https://github.com/python-caldav/caldav/issues/397 - Recurrence instances gets stripped when doing cal.object_by_uid(uid,comp_class=caldav.Event) - Estimate: 2h |
| 185 | +* https://github.com/python-caldav/caldav/issues/439 - Test fails against radicale - Estimate: 2h |
| 186 | +* https://github.com/python-caldav/caldav/issues/477 - Deprecation warnings on vobject - Estimate: 1h |
| 187 | + |
| 188 | +### 3.0 milestone |
| 189 | + |
| 190 | +* https://github.com/python-caldav/caldav/issues/372 - timezones problem - Estimate: 5h |
| 191 | +* https://github.com/python-caldav/caldav/issues/398 - look more into recurrences - Estimate: 5h |
| 192 | +* https://github.com/python-caldav/caldav/issues/399 - problems with accept_invite at some servers - Estimate: 2h |
| 193 | + |
| 194 | +### Later |
| 195 | + |
| 196 | +* https://github.com/python-caldav/caldav/issues/35 |
| 197 | +* https://github.com/python-caldav/caldav/issues/152 |
| 198 | +* https://github.com/python-caldav/caldav/issues/425 |
| 199 | +* https://github.com/python-caldav/caldav/issues/420 |
0 commit comments