Add custom reminder extension and use that for calendar syncing

[mpcjanssen]

As raised in #192 by @smichel17 a general reminder extension could be introduced which also allows specification of a time and which would be automatically synchronized with the calendar.

1. Remove the current automatic calendar reminder feature entirely.
2. Support a new extension: rem:YYYY-MM-DD:HH:MM. (edit: or just r: instead of rem:)
   • Any task with this extension will have a calendar reminder be created on that date at that time.
   • If no time is given (just rem:YYYY-MM-DD), add it to the calendar but do not set any reminders.
   • Multiple reminders work fine. If they're on different days, create multiple calendar appointments for those days. If they're on the same day, create a single appointment with multiple reminders.
   • Repurpose the "Set Reminder" functionality so instead of opening the calendar app, it adds a reminder to the task.
     • Add an option to clear all reminders.
3. Optional: remove support for the due: extension -> people should use the rem: extension instead.
   • Alternative: Don't use rem:, but instead change due: to work the way rem: was described.
   • I wanted to include this here because it's related content-wise, but there's another discussion we should have about design philosophy before we talk about it. I'll make a separate issue about that. #465

[smichel17]

Also from #192 by @krayon, an improvement on what this todo.txt extension should look like:

Regarding date formats, currently YYYY-MM-DD complies with ISO8601 ( https://en.wikipedia.org/wiki/ISO_8601 ) and I would encourage continued compliance regardless of what solution is chosen. This taken the form YYYY-MM-DD'T'HH:MM ('T' being literal), eg: 2016-06-25T00:33. Standards == Good.

[smichel17]

The proposal quoted above was (1) Remove automatic calendar reminder functionality, and (2) Replace current "add reminder" functionality with a todo.txt extension as described above.

It occurs to me that we don't strictly need to do (1) in order to do (2), although (1) adds additional complexity to simpletask so if (2) covers everyone's needs I'd be in favor of doing (1) anyway.

[vojtechkral]

The ISO format was what I proposed in one of the old threads as I recall.

But more to the point, this doesn't work well with my workflow. Usually I want reminders for tasks that are due far in the future (such as appointments, meetings, payments, etc.). With the rem extension as proposed, I'd have to fill in twice as much information - the due date (and often also time) and also the reminder date and time.

The multiple reminders suggestion also sounds quite complex.

[jumper047]

@vojtechkral, I think break compatibility with original format is bad idea. May be it is possible to add due: and rem: with one action, with checkbox "add reminder" in due picker.

[smichel17]

@vojtechkral:

Complex from a UX perspective or a backend perspective?

If a due date is set for a task, there should be an "on due date" option for the reminder to make that quicker.

More to the point: can you tell me about your workflow? What kind of reminders do you want to set and why not say them through your calendar, aside from calendar applications being not up to par?

[mpcjanssen]

I think this should be an additional check box beside threshold and due date.

[mpcjanssen]

How about a part of the Lua script that allows a reminder date and time to be calculated from any task, so analogous to filtering due and threshold can be used from UI, anything else can be used from Lua and takes precedence over the UI setting.

[vojtechkral]

@smichel17

Complex from a UX perspective or a backend perspective?

Mostly UX.

More to the point: can you tell me about your workflow? What kind of reminders do you want to set and why not say them through your calendar, aside from calendar applications being not up to par?

Quite often I need to create task due far in the future, such as a payment, meeting or a doctor appointement several months in the future. One forgets about that easily. I need to record what exactly is the date/time of the task, but I also like the phone to remind me few days before that in case I forget or fail to notice it in the todo.

Of course, the calendar is the right place to do this and I should probably use it. The bad UX of the calendar apps is the only thing in the way.

BTW. I had a look at the Etar/AOSP calendar code and it's quite complex. Some 60k lines of code :-/ I'll see what can be done...

[vojtechkral]

@mpcjanssen That's actually a good idea. I'd even

[vojtechkral]

It might be even better to move reminders to Lua altogether and perhaps provide some examples / default sync scripts or the like.

[mpcjanssen]

@vojtechkral it's the lazy option, but it does make sense. However I think providing due date sync by default makes sense as it's probably the most used. So the sync setting would be on of:

1. due date
2. Lua script onCalendarSync(taskTable) which returns a timerange

[mpcjanssen]

Will be implemented as part of #349

[vojtechkral]

@mpcjanssen Ok. The Lua API should probably be per-task (I suppose?) Ie. a Lua function called for each task that would return either nil for no calendar data or a datetime for event and optionally datetime(s) for reminders.

[mpcjanssen]

@vojtechkral there would be one callback which returns a time range for every task and if this is not nil create a calendar item for it.

[smichel17]

@mpcjanssen An additional check box in the settings? Why? If you add a reminder, it's because you want a reminder. if you don't, just don't add any reminders. There's no need for a global enable/disable. That's one of the reasons why this solution is simpler.

---

@vojtechkral

Mostly UX.

I really don't follow what is confusing about "rem:YYYY-MM-DD'T'HH:MM adds a reminder for that task at the specified date time". I also don't see what's confusing about the workflow of "select task -> 'add a reminder' -> date picker -> time picker -> reminder is added" or "select task -> 'remove reminders' -> all reminders for that task are removed'

Of course, the calendar is the right place to do this and I should probably use it. The bad UX of the calendar apps is the only thing in the way.

It wouldn't be appropriate to turn Simpletask's issues section into a list of grievances, so I forked etar (and added you as a contributor); I'd be interested in hearing what issues you have with it, over in its issues section.

BTW. I had a look at the Etar/AOSP calendar code and it's quite complex. Some 60k lines of code :-/ I'll see what can be done...

I have looked at it in the past as well and... yeah, not the friendliest code base. On the upside, maybe we can cut out a bunch! I only use a pretty basic feature set.

[smichel17]

Quoting myself from #465 with a few wording changes for clarity

I am a big fan of scripting in this case. It basically says, "There is a certain way Simpletask is meant to be used, and we will only support that way... but we recognize that you might want to use Simpletask in a way it's not intended. We won't support that, but we will support you in building that functionality yourself."

I think it might also make sense to maintain a repository of lua scripts that people can easily download and use. For example, I think we should remove most or all calendar reminder functionality from the core of the app, but that would break some people's workflows. So instead we should remove the functionality and also provide a ready-made script that re-implements the removed functionality, so people who depend on that workflow aren't left out.

Also, if there's a way to track how often each script is downloaded, it lets us get some usage statistics without putting tracking into the app itself, which I find morally objectionable unless it's opt-in -- and if it's opt-in it's much less useful.

[vojtechkral]

@mpcjanssen

there would be one callback which returns a time range for every task and if this is not nil create a calendar item for it.

Ok, great. Let me know later on how I should connect that to my code.

@smichel17

I really don't follow what is confusing about "rem:YYYY-MM-DDTHH:MM adds a reminder for that task at the specified date time". I also don't see what's confusing about the workflow of "select task -> 'add a reminder' -> date picker -> time picker -> reminder is added" or "select task -> 'remove reminders' -> all reminders for that task are removed'

It's not confusing or bad or anyhting, it's just that with the current solution I don't have to do any of that. (Of course, the current solution has a bunch of other problems, but that's another thing...)

[vojtechkral]

@smichel17

It wouldn't be appropriate to turn Simpletask's issues section into a list of grievances, so I forked etar (and added you as a contributor); I'd be interested in hearing what issues you have with it, over in its issues section.

Ok, thanks. I have a design in mind, I'll let you know. Implementation-wise, I'd like to simplify and write any new code in Kotlin if at all possible. However, bear in mind please that this won't be any time soon, I first have to finish the calendar sync changes in Simpletask.

[mpcjanssen]

I think part of the reason Simpletask development has sped up recently again is because I am using Kotlin, it's much more fun to write, less verbose and more expressive. It also prevents a huge class of errors by design (NPE).

Note that with the onCalendarSync from #349, the user can decide themselves which date they want to use. See wiki page for details.

[vojtechkral]

@mpcjanssen I've had a look at the wiki page and it's not clear to me what the onCalendarSync return value means. Is that the timespan of the event or the reminder?

[mpcjanssen]

@vojtechkral that's the timespan of the calendar event that is created. If there should be a separate reminder as well than that needs to be an additional return. Please let me know what values you would need in the syncing functionality

[smichel17]

@mpcjanssen @vojtechkral There's a design decision here about what functionality simpletask should have. The most advanced functionality I could see us supporting would be return values of:

• All day appointment? (bool)
• Start date/time
• End date/time
• Contents of reminder (you usually don't need due:YYYY-MM-DD in a calendar appointment. Sometimes you want lists/tasks to be included, sometimes not).
• List of reminders to be created as time-from-start-time.

Doing all that would be a lot. My personal preferences are:

• All day appointment? (bool)
  • Don't include this. All appointments should be all-day appointments.
• Start date/time
  • Include this
• End date/time
  • Don't include this. All appointments should be a single day (end date=start date).
• Contents of reminder (you usually don't need due:YYYY-MM-DD in a calendar appointment. Sometimes you want lists/tasks to be included, sometimes not).
  • Probably don't need to include this, but we should come up with better logic about what is included/excluded.
• List of reminders to be created as time-from-start-time.
  • Include this. People like reminders at different times, and not necessarily with all reminders at the same time.

[vojtechkral]

@mpcjanssen In the calendar API, reminders have to always be entered separately for each event. They have their own table in the sqlite file.

@smichel17 I'd agree with that list. The all day boolean flag is not needed if we say that an all day event has a start time = midnight and an end time of start time + 24 hours (the next midnight). This is required by the calendar API for all day events anyway.

We could proably also limit the number of reminders to just one, so that the callback return data would be: event start & end datetime (if any) and a reminder datetime (if any).

[mpcjanssen]

@vojtechkral @smichel17 I will try to updated the wiki description when I have time. Note that I prefer to give a bit more (optional) returns than to reduce flexibility. Return value for the onCalendarSync will probably be a table.

[smichel17]

It's fine to offer all of those as returns as long as they are optional, with the defaults I mentioned above.

[mpcjanssen]

Will implement a reminderDate configuration function in a next version which will return the required information. If set it will override the selection from the settings.

[smichel17]

Rethinking Reminders

If you just want to see my conclusion, skip to the final paragraph.

Reminders are for your protection

Some tasks have a time range in which they should be done.

• Filing taxes
• Repairs under warrantee
• Phone calls
• Limited time events

GTD also says you should track these items as tasks, and presumably prioritize them more highly as you near the deadline. But unlike most items in Simpletask, it's a big deal if you forget about one. Reminders exist so you won't forget.

Reminder strength

• Tasks in simpletask or a notepad are weak reminders.
• Non-persistent notifications are mild reminders.
  • These are good for things you don't want to slip your mind. Ex: as a reminder that you need to file taxes soon.
• Persistent notifications are medium strength reminders
  • These are what's left for tasks with due dates -- stronger than a "don't forget this" reminder but not as strong as a calendar appointment.
• Noisy alerts are strong reminders.
  • Reserve these for calendar appointments
  • Reserve those for true appointments (including ones with yourself).

Automatic Reminders are for Jill

Bob reviews his calendar and his task list each morning and uses them to plan out his day. During his review, he blocks out time in his calendar for each task that is due that day. Bob doesn't need automatic reminders, because he pays attention to the weak reminders.

Jill isn't quite as disciplined. She reviews her list regularly, but not every day. And she often forgets to look at her calendar, relying instead on the notifications she sets on calendar appointments. Jill needs automatic reminders because she doesn't always pay attention to her weak reminders.

Calendar? Reminders

GTD suggests using your calendar for reminders. That's fine if you're using a paper calendar, but calendar apps are designed around appointments, which all reminders are attached to. No due dates. And reminders only have one (awkward) form: an alert (strong reminder) coupled with a non-persistent notification (mild reminder). Finally, the current implementation tries to set every reminder at the same time, although that's not ideal. That's why the current simpletask implementation requires such hacks and feels so awkward. It's a flimsy square peg in a round hole.

Aside: @vojtechkral I'm particularly curious what you think about the idea that calendar apps are fundamentally incompatible with due dates.

Principles

• Lua should be an optional enhancement, not a requirement.
  • We should support reminders natively, not only with lua.
• User Experience matters, not the tools we use to provide that experience.
  • The calendar is a tool. If it doesn't work well, we should consider alternatives.
  • Automation is a tool. If the manual way works better, we should do it.
• [Unix] One tool should do one job well
  • Simpletask should not try to recreate the strengths of a calendar (scheduling time blocks)
  • Simpletask should not try to force a calendar to do things besides scheduling time blocks.

Conclusion / Suggested Implementation

• For tasks with due dates, when that date comes, there should be a notification with the task in it that will persist until the task is complete. You might be able to borrow some code from OpenTasks. Tap the...
  • [Notification]: Open Simpletask with that task selected.
  • [First action]: Mark task as complete
  • [Second action]: Schedule a calendar appointment (currently, "Set reminder")
• For any task, you should be able to manually set any number of reminders. Each reminder should create a non-persistent notification (swipe to dismiss, tap to open simpletask with that task selected).
  • Uses the rem:YYYY-MM-DD'T'HH:MM format discussed in this thread.
  • You'll be able to set these automatically with lua if you want to, say, add a reminder 2, 4, and 7 days before each task with a due date.
  • Could optionally include an alert, if the notification is set to low priority. Seems like something to add later, not initially.
  • This answers the question of #192. No, you should not provide a time picker.
• Retain the ability (currently named "Set Reminder") to manually create appointments on your normal calendar based on tasks.
  • Rename it to "Create Appointment" or "Add to calendar"
  • Actually we won't need to name it at all; with #128 it'll be an icon.

[vojtechkral]

@smichel17

Aside: @vojtechkral I'm particularly curious what you think about the idea that calendar apps are fundamentally incompatible with due dates.

Well, your're right, the Calendar is appointment-centric and has no "standalone" reminders. And as such it's awkward to use for I-just-want-a-reminder types of thing.

A notification that persists until a task is complete sounds good. However I remember @mpcjanssen not liking the idea of Simpletask doing notifications (which is understandable).

Maybe the simplest solution would be to become Bob (rather than Jill), but I'm not sure I'm capable of that :-)

[smichel17]

@vojtechkral Your memory is correct. @mpcjanssen said this in #199:

I won't add notifications to Simpletask. I think it's the wrong tool for the job.

I hope my previous essay-of-a-comment convinces him that

• It's important to have reminders for projects that are ongoing but also have a due date.
• Calendars are the wrong tool for setting reminders. (They are the right tool for setting appointments, ie, scheduling)
• Notifications are the right tool for reminders.

Therefore, since Simpletask is the place to track projects of that type, it should set notifications.

It's possible we could pass this off to a different dedicated reminder app like we have been with the calendar, but I don't know of any dedicated reminder apps (and there won't ever be, because that app would have almost no functionality outside of setting notifications... at which point, why not just set notifications yourself?).

[mpcjanssen]

I am leaning towards keeping the current implementation in the settings and adding a flexible Lua callback which will allow the user to set the calendar appointment however he/she wants.

[smichel17]

@mpcjanssen There's a different between (1) an appointment you make with yourself, (2i) a reminder for something in the future, and (2ii) an urgent reminder of something you need to do RIGHT NOW.

1. "I'm planning to work on project A from 9:30-11:30 tomorrow."
   • This is something you should manually add to your calendar.
   • Simpletask is not a calendar app and should not ever provide an interface for doing this, manually OR automatically.
     • We should make it easy to use your calendar's interface to do this. We already do this well via an intent.
2. 1. "Note to self: the deadline for your taxes is coming up; don't forget about it."
      • This is what threshold reminders is trying to be. Due reminders for a few days ahead of time tries to be this, too.
      • Automatically populating a calendar with alerts is a reasonable implementation.
      • However, it drains battery life.
      • If simpletask created its own notifications, we would not have to maintain a calendar or other list of upcoming appointments; only the single next one, and when that one plays we can determine when the one after that should play.
      • However, there is no graphical interface to see what reminders you've set for yourself. I don't think this is a big deal, since they are just reminders; if you remember to go look ahead on your calendar to see what reminders you have set (ie, if you're Bob), you can also remember to go look at your todo list, and then you'll be reminded of your upcoming taxes anyway.
   2. "YOUR TAXES ARE DUE TODAY; FINISH THEM NOW."
      • This is what Due reminders is trying to be.
      • A calendar notification is not good for this because you can easily dismiss it.
      • A calendar notification is not good for this because you can't predict what the right time for an alert is.
      • This should be in a notification that cannot be dismissed (without killing simpletask) until the task is complete.

Does that make sense?

[roman-yagodin]

I think the reminder/notification system would be great thing. The current implementation is almost useless - at least for me, as I certainly will not remember anything at the noon that I've been reminded about something at the morning...