“Repeat every year” sounds like a simple instruction—until the original date is February 29.
While contributing to Super Productivity, I worked on a recurrence bug involving a task that started on a leap day. In a non-leap year, the application could create an extra overdue task before the next occurrence was due.
Duration arithmetic measures elapsed time. Calendar arithmetic models human schedules.
Those concepts overlap on ordinary dates, but they can produce different answers around leap years, month boundaries, daylight-saving transitions, and multi-year recurrence rules.
Because February 29 does not exist every year, the application needed a policy for non-leap years. In this case, the intended behavior was:
In the failing path, setting the day to 29 on a February 2025 date overflowed to March 1. The calculation then stepped back one year while preserving March 1, making March 1, 2024 appear later than the already-created February 29, 2024 occurrence.
That disagreement caused the application to materialize another overdue 2024 task.
The visible problem was a duplicate task, but the underlying problem was more interesting: different parts of the scheduling logic disagreed about which calendar occurrence existed.
JavaScript’s Date setters normalize out-of-range components instead of rejecting them.
There is no February 29 in 2025, so JavaScript carries the extra day into March.
This behavior is valid and sometimes useful. But it is not necessarily the recurrence policy your product intends.
For a yearly task, several behaviors could be reasonable: Move the occurrence to February 28. Move it to March 1. Skip non-leap years. Ask the user to select a policy.
The important part is not choosing one universally correct answer. The important part is making the rule explicit and applying it consistently.
Super Productivity’s expected rule was to clamp the date to the last valid day of the month: February 28.
But that assumes every year represents the same duration. Leap years immediately break that assumption.
Duration math is appropriate for questions such as: Has a 30-minute timeout expired? How long did this request take? Has a 24-hour retention period passed?
Calendar math is more appropriate for: Repeat this task every year. Run payroll on the last day of each month. Renew this subscription every three months. Schedule an event every Monday. Trigger an anniversary reminder.
A recurring task expresses human calendar intent. It is not merely a number of milliseconds after another timestamp.