Custom recurrence

[aigoncharov]

Hello,

I am wondering what would be the best way to approach custom recurrence rules?
Currently, the plugin supports only a set of periodic rules, which, while useful, might not cover the full extent of what people might want to do.

A good example is spaced repetition - a popular learning pattern.

As discussed in #2961, it is not feasible from the maintenance point of view to keep adding the new recurrence rules to the core. Should it be something an extension to the plugin might do?

Potential requirements for the extension API

• [P0] Minimalistic API. This way, it is easy to change the underlying implementation without breaking compatibility.
• [P0] Allow for multiple custom recurrence rules
• [P1] Allow overriding the default recurrence rule
• [P2] Allow to add entries to the default list of autocompletion suggestions

Proposed implementation

1. Create a minimalistic API that every recurrence (including the current default one) should conform to

interface AbstractRecurrence {
    readonly startDate: Moment | null;
    readonly scheduledDate: Moment | null;
    readonly dueDate: Moment | null;

    toText(): string;
    next(today: Moment): AbstractRecurrence | null;
    identicalTo(other: AbstractRecurrence): boolean;

   static fromText(data: {
        recurrenceRuleText: string;
        startDate: Moment | null;
        scheduledDate: Moment | null;
        dueDate: Moment | null;
    }): AbstractRecurrence | null;
}

2. Create a singleton registry with all available recurrences.

interface RecurrenceRegistry {
    addToRecurrenceRegistry(recurrenceDefinition: new() => AbstractRecurrence): void
    parseRecurrenceFromText(data: {
        recurrenceRuleText: string;
        startDate: Moment | null;
        scheduledDate: Moment | null;
        dueDate: Moment | null;
    }): AbstractRecurrence
}

3. Expose the registry via API

interface APIV1 {
           addCustomRecurrence(recurrenceDefinition: new() => AbstractRecurrence): void
}

Potential usage example

// In some other plugin that, say, wants to add spaced repetition ;)

class SpacedRepetitionRecurrence extends AbstractRecurrence {
    private readonly spacedRepetitionProgression = [1, 3, 10];
    private readonly repetition: number;

    public toText() {
       return `spaced_${this.repetition}`
    }
    public next(today: Moment) {
       // calculate the next instance based on the pattern
    }
    public identicalTo(other: AbstractRecurrence) { ... }

    static fromText(data) {
       // parse text to create an instance of SpacedRepetitionRecurrence
    }
}

const tasksApi = this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1;
tasksApi.addCustomRecurrence(SpacedRepetitionRecurrence)

Pros / cons

Pros:

• Allows for great flexibility as the pubic interface requires implementing only 4 methods: toText, fromText, next, identicalTo.

Cons:

• Potential of the code inside of the existing Recurrence class.
• The current proposal exposes only programmatic access and not the UI. However, one could build a UI on top of it if necessary.

Draft implementation

#2963

[claremacrae]

Thanks very much for kicking this off, @aigoncharov - and for your code and ideas so far....

I am wondering what would be the best way to approach custom recurrence rules? Currently, the plugin supports only a set of periodic rules, which, while useful, might not cover the full extent of what people might want to do.

A good example is spaced repetition - a popular learning pattern.

As discussed in #2961, it is not feasible from the maintenance point of view to keep adding the new recurrence rules to the core. Should it be something an extension to the plugin might do?

(Lots of comments that were here are now moved out to separate sections below...)

Code for the settings editor

Don't worry about the implementation of the editing widget for now, because:

• it's a waste of time if we don't manage to agree a way forward
• the Custom Status settings code will give a good starting point - it's non-obvious, so I would want to explain how to adjust it, rather than having a new mechanism provided... but I don't have time to write that up now anyway...

[claremacrae]

(Please don't reply here - I have divided original text from above up in to single comments below, so we can try and group together discussion on each separate topic...)

[claremacrae]

Documentation and Tests

I forgot to say, a long time ago, I used to be able to offer to write documentation for new features, where the author was not comfortable writing the docs.

The volume of work on Tasks these days is such that that approach no longer works.

I am happy to copy-edit a first draft of user docs, if need be - but not to write the docs from scratch.

For large facilities like this one, a good way of doing the design and planning is for the contributor to write a first draft of the user docs before doing the implementation, as this confirms that it can even be described to users in an understandable way, and can lead to improvements in UI before implementation....

[claremacrae]

And the same applies to unit tests. I've found that PRs that don't have meaningful automated tests invariably end up requiring too much of my time on bug-fixing time in order to shepherd them to release.

In this past I have sometimes merged PRs from users who didn't have experience in writing effective automated tests, and then set about adding tests. And invariably I have then been diverted from my own project work in order to fix bugs that I found when writing tests, sometimes blocking me from release Tasks for many weeks.

So - for transparency - thorough test coverage, and not just of the "happy paths" would also be a precursor to a PR...

Should this project go ahead, @aigoncharov, we can offer guidance on test-writing if that is something new to you - it's a speciality of both myself and @ilandikov...

[claremacrae]

The 🔁 signifier and its values

(This time, a single topic in a comment, to make tracking responses easier - was too tired to think of that last night...)

I wonder what the Tasks signifiers/lines would look like, for custom recurrence rules.

I'm asking because someone has kindly produced a proof-of-concept for a rewrite of the Tasks plugin reading and writing of task lines... - and the problem they had was finding a general way to identify the end of recurrence text, as the current syntax is so flexible... Every other field was relative easy.

So I'm keen for new features not that make that event rewrite any harder than it already is.

A current example is:

🔁 every 14 days when done

All the recurrences begin every now...

I can't see how to make every fit with custom rules, though.

So a first idea would be to offer two options:

🔁 custom my-lovely-recurrence-pattern
🔁 custom my-lovely-recurrence-pattern when done

And to define and document the allowed characters in a custom recurrence patter, disallowing spaces for easy or parsing...

Here is how I did similar docs previously - for the id field.

And somewhere in the code there is a single-source-of-truth as to the allowed characters in IDs.

Any more thoughts?

[claremacrae]

Overview of the envisaged feature - for discussion!

Background

I think the thought process so far (or my understanding of it) has gone something like:

1. I considered Spaced Repetition is too specialised a concept, and not something to be implemented in core Tasks.
2. So @aigoncharov proposed instead one or two possible API approaches
3. We don't have the capacity to apply to designing new APIs currently - we are focussing on improving the core foundations of the plugin - so it (APIs) aren't something that I would advocate making any firm decisions, nor doing any implementation of, in the foreseeable future.
4. @ilandikov then had the lovely idea of seeing a more general facility than Spaced Repetition, namely the possibility for "ordinary" Tasks users to be able to define:
   • one or more custom recurrence rules, in core Tasks code
   • and give the recurrence rules names
   • and save the custom rules in settings
5. I see this idea as something that would be really beneficial to Tasks users, so would be happy for an implementation to be added to core Tasks. In which case, an API approach is the wrong level of user-facing facility anyway, or at least, not the initial priority....

Initial thoughts

I see it as having some similarities with Custom Statuses, in that:

• there is a list of user-defined settings
• that have names
• it gives users a lot of control over the behaviour of the plugin.

It's just that they would be defining one or more recurrence rules, instead of statuses...

Also, just as the Custom Statuses have buttons for some pre-prepared sets of statuses, so there might be pre-prepared Recurrence rules like "Spaced Repetition", that is easy for users to add, and then optionally edit.

Does that make sense? Does it need a picture?
Are there any other ideas?

[claremacrae]

Ideas for example custom repetition rules

Before deciding on the detail, I would like to see suggestions of other possible patterns.

[claremacrae]

The first example being 'Spaced Repetition', of course...

[claremacrae]

• Repeat every week, for 15 weeks
  • Add support for recurrence rules containing 'for n times' #1729

[claremacrae]

What the ingredients are for a custom recurrence rule/pattern

This is one area that is going to need a lot of thought. Once we have some ideas for patterns, then there needs to be a proposal for how a rule would be defined...

Is a rule something as simple as:

• upon completion 1, create a next recurrence 2 days ahead
• upon completion 2, creation next recurrent 5 days ahead
• upon completion 3, just completed the task...

And then thoughts on how to present an editor UI for a rule....

[claremacrae]

I wonder whether all custom rules can be implemented (behind the scenes) in terms of the existing built-in rules.

For example:

• upon completion 1, create a next recurrence 2 days ahead
  • every 2 days when done
• upon completion 2, creation next recurrent 5 days ahead
  • every 5 days when done
• upon completion 3, just completed the task...
  • complete the task, and maybe delete the next recurrence

[claremacrae]

How to track the number of completions...

For this to be viable, there needs to be a safer way than in #2961 to keep track of the number of recurrences so far...

Appending a number to the description will be problematical for descriptions like:

read a chapter of Book Blah, Volume 3

If you search the existing Issues and Discussions for Open and Closed tickets with the same label as this one, you will see previous discussions and requests, which might give ideas....

[aigoncharov]

Thank you for providing so much detailed information! I think it is going to be a great foundation for anyone who wants to tackle it, but it is probably not going to be me this time.

We don't have the capacity to apply to designing new APIs currently - we are focussing on improving the core foundations of the plugin - so it (APIs) aren't something that I would advocate making

In my personal view, adding any DSL to support custom recurrence via UI would go against "improving the core foundations". First, it is yet another complex feature to support. Second, it is still going to be lacking flexibility compared to a programmatic API usage.

IMHO, the plugin should focus on parsing, querying, displaying, and editing tasks, and provide a rich API for other developers to build on top of it. This would make it easier to support the plugin long-term as the new features would be the responsibility of others. Also, it would potentially support more use-cases as developers start adopting the API.

Having said that, I totally get where you are coming from. I absolutely admire your deep care for the users and other contributors. Thank you very much for all your hard work on this amazing piece of software!

[claremacrae]

Thanks for the message @aigoncharov and apologies for the late reply.

When we reach the stage to work on the API (and we will), I'll get back and seek your input in its design, as I am sure it will help us out a lot. You clearly have a lot more experience in this area than I do.