Skip to content

Commit

Permalink
docs: Add appendix showing date filter changes (#1784)
Browse files Browse the repository at this point in the history 
* docs: First attempt at documenting the changes in date search results in next release

* docs: Summarise the changes in behaviour

* docs: More logical order of sections in appendix

* docs: Add links to/from new appendix sections
  • Loading branch information
@claremacrae
claremacrae committed Mar 22, 2023
1 parent 6dc959a commit 34d8eb2
Showing 1 changed file with 81 additions and 0 deletions.
81 changes: 81 additions & 0 deletions docs/queries/filters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,10 @@ Example absolute date ranges:

- `2022-01-01 2023-02-01`

{: .warning }
Prior to Tasks 1.26.0, the second date in absolute date ranges was ignored.
See the tables in the [Appendix below]({{ site.baseurl }}{% link queries/filters.md %}#appendix-tasks-1260-improvements-to-date-filters) to understand the changes in results, and whether you need to update any of your searches.

### Relative date ranges

Tasks supports a very specific set of relative `<date range>` values: `last|this|next week|month|quarter|year`. The pipe (`|`) character means 'or'.
Expand All @@ -113,6 +117,10 @@ Example relative date ranges:
- `next quarter`
- `before next year`

{: .warning }
Prior to Tasks 1.26.0, the interpretation of relative date ranges was confusing, and not what most users naturally expected.
See the tables in the [Appendix below]({{ site.baseurl }}{% link queries/filters.md %}#appendix-tasks-1260-improvements-to-date-filters) to understand the changes in results, and whether you need to update any of your searches.

### Troubleshooting date searches

If your date searches are giving unexpected results, add an [`explain`]({{ site.baseurl }}{% link queries/explaining-queries.md %}) line to your query.
Expand Down Expand Up @@ -524,3 +532,76 @@ Note that the file name includes the `.md` extension.

{: .released }
`regex matches` and `regex does not match` were introduced in Tasks 1.12.0.

## Appendix: Tasks 1.26.0 improvements to date filters

Tasks 1.26.0 introduced the concept of filtering for date ranges.

In all cases, this new feature improves the results of Tasks date filters.

This Appendix shows how the results of various searches have changes, to enable you to decide whether any existing searches need to be updated.

### due (before|on|in||after) absolute date: results unchanged

Unchanged interpretation of various [**absolute** due date]({{ site.baseurl }}{% link queries/filters.md %}#absolute-dates) filters:

| keyword | Tasks 1.25.0 and earlier | Tasks 1.26.0 onwards |
| ----------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Summary** | All searches behave logically, using the correct date. | Identical behaviour to previous releases. |
| `before` | `due before 2023-02-09` =><br> due date is before<br>2023-02-09 (Thursday 9th February 2023)<br> | `due before 2023-02-09` =><br> due date is before<br>2023-02-09 (Thursday 9th February 2023)<br> |
| `on` | `due on 2023-02-09` =><br> due date is on<br>2023-02-09 (Thursday 9th February 2023)<br> | `due on 2023-02-09` =><br> due date is on<br>2023-02-09 (Thursday 9th February 2023)<br> |
| `in` | `due in 2023-02-09` =><br> due date is on<br>2023-02-09 (Thursday 9th February 2023)<br> | `due in 2023-02-09` =><br> due date is on<br>2023-02-09 (Thursday 9th February 2023)<br> |
| | `due 2023-02-09` =><br> due date is on<br>2023-02-09 (Thursday 9th February 2023)<br> | `due 2023-02-09` =><br> due date is on<br>2023-02-09 (Thursday 9th February 2023)<br> |
| `after` | `due after 2023-02-09` =><br> due date is after<br>2023-02-09 (Thursday 9th February 2023)<br> | `due after 2023-02-09` =><br> due date is after<br>2023-02-09 (Thursday 9th February 2023)<br> |

### due (before|on|in||after) absolute date range: results improved

Differences in interpretation of various [**absolute** due date **range**]({{ site.baseurl }}{% link queries/filters.md %}#absolute-date-ranges) filters:

| keyword | Tasks 1.25.0 and earlier | Tasks 1.26.0 onwards |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Summary** | The second date is ignored: only the first date is used. | The values are interpreted as a date range.<br>`after` takes the end date in to account. |
| `before` | `due before 2023-02-07 2023-02-11` =><br> due date is before<br>2023-02-07 (Tuesday 7th February 2023)<br> | `due before 2023-02-07 2023-02-11` =><br> due date is before<br>2023-02-07 (Tuesday 7th February 2023)<br> |
| `on` | `due on 2023-02-07 2023-02-11` =><br> due date is on<br>2023-02-07 (Tuesday 7th February 2023)<br> | `due on 2023-02-07 2023-02-11` =><br> due date is between<br>2023-02-07 (Tuesday 7th February 2023) and<br>2023-02-11 (Saturday 11th February 2023) inclusive<br> |
| `in` | `due in 2023-02-07 2023-02-11` =><br> due date is on<br>2023-02-07 (Tuesday 7th February 2023)<br> | `due in 2023-02-07 2023-02-11` =><br> due date is between<br>2023-02-07 (Tuesday 7th February 2023) and<br>2023-02-11 (Saturday 11th February 2023) inclusive<br> |
| | `due 2023-02-07 2023-02-11` =><br> due date is on<br>2023-02-07 (Tuesday 7th February 2023)<br> | `due 2023-02-07 2023-02-11` =><br> due date is between<br>2023-02-07 (Tuesday 7th February 2023) and<br>2023-02-11 (Saturday 11th February 2023) inclusive<br> |
| `after` | `due after 2023-02-07 2023-02-11` =><br> due date is after<br>2023-02-07 (Tuesday 7th February 2023)<br> | `due after 2023-02-07 2023-02-11` =><br> due date is after<br>2023-02-11 (Saturday 11th February 2023)<br> |

### due (before|on|in||after) last week: results improved

Differences in interpretation of various [**relative** due date **range**]({{ site.baseurl }}{% link queries/filters.md %}#relative-date-ranges) filters, when run on `2023-02-10` (Friday 10th February 2023):

| keyword | Tasks 1.25.0 and earlier | Tasks 1.26.0 onwards |
| ----------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Summary** | `last week` is interpreted as a single date:<br> `7 days before the current date`. | `last week` is interpreted as a date range:<br>the previous `Monday to Sunday`.<br>`after` takes the end date in to account. |
| `before` | `due before last week` =><br> due date is before<br>2023-02-03 (Friday 3rd February 2023)<br> | `due before last week` =><br> due date is before<br>2023-01-30 (Monday 30th January 2023)<br> |
| `on` | `due on last week` =><br> due date is on<br>2023-02-03 (Friday 3rd February 2023)<br> | `due on last week` =><br> due date is between<br>2023-01-30 (Monday 30th January 2023) and<br>2023-02-05 (Sunday 5th February 2023) inclusive<br> |
| `in` | `due in last week` =><br> due date is on<br>2023-02-03 (Friday 3rd February 2023)<br> | `due in last week` =><br> due date is between<br>2023-01-30 (Monday 30th January 2023) and<br>2023-02-05 (Sunday 5th February 2023) inclusive<br> |
| | `due last week` =><br> due date is on<br>2023-02-03 (Friday 3rd February 2023)<br> | `due last week` =><br> due date is between<br>2023-01-30 (Monday 30th January 2023) and<br>2023-02-05 (Sunday 5th February 2023) inclusive<br> |
| `after` | `due after last week` =><br> due date is after<br>2023-02-03 (Friday 3rd February 2023)<br> | `due after last week` =><br> due date is after<br>2023-02-05 (Sunday 5th February 2023)<br> |

### due (before|on|in||after) this week: results improved

Differences in interpretation of various [**relative** due date **range**]({{ site.baseurl }}{% link queries/filters.md %}#relative-date-ranges) filters, when run on `2023-02-10` (Friday 10th February 2023):

| keyword | Tasks 1.25.0 and earlier | Tasks 1.26.0 onwards |
| ----------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Summary** | `this week` is interpreted as a single date:<br>`the sunday before the current date` | `this week` is interpreted as a date range:<br>the `Monday to Sunday containing the current day`.<br>`after` takes the end date in to account. |
| `before` | `due before this week` =><br> due date is before<br>2023-02-05 (Sunday 5th February 2023)<br> | `due before this week` =><br> due date is before<br>2023-02-06 (Monday 6th February 2023)<br> |
| `on` | `due on this week` =><br> due date is on<br>2023-02-05 (Sunday 5th February 2023)<br> | `due on this week` =><br> due date is between<br>2023-02-06 (Monday 6th February 2023) and<br>2023-02-12 (Sunday 12th February 2023) inclusive<br> |
| `in` | `due in this week` =><br> due date is on<br>2023-02-05 (Sunday 5th February 2023)<br> | `due in this week` =><br> due date is between<br>2023-02-06 (Monday 6th February 2023) and<br>2023-02-12 (Sunday 12th February 2023) inclusive<br> |
| | `due this week` =><br> due date is on<br>2023-02-05 (Sunday 5th February 2023)<br> | `due this week` =><br> due date is between<br>2023-02-06 (Monday 6th February 2023) and<br>2023-02-12 (Sunday 12th February 2023) inclusive<br> |
| `after` | `due after this week` =><br> due date is after<br>2023-02-05 (Sunday 5th February 2023)<br> | `due after this week` =><br> due date is after<br>2023-02-12 (Sunday 12th February 2023)<br> |

### due (before|on|in||after) next week: results improved

Differences in interpretation of various [**relative** due date **range**]({{ site.baseurl }}{% link queries/filters.md %}#relative-date-ranges) filters, when run on `2023-02-10` (Friday 10th February 2023):

| keyword | Tasks 1.25.0 and earlier | Tasks 1.26.0 onwards |
| ----------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Summary** | `next week` is interpreted as a single date:<br> `7 days after the current date`. | `next week` is interpreted as a date range:<br>the next `Monday to Sunday`.<br>`after` takes the end date in to account. |
| `before` | `due before next week` =><br> due date is before<br>2023-02-17 (Friday 17th February 2023)<br> | `due before next week` =><br> due date is before<br>2023-02-13 (Monday 13th February 2023)<br> |
| `on` | `due on next week` =><br> due date is on<br>2023-02-17 (Friday 17th February 2023)<br> | `due on next week` =><br> due date is between<br>2023-02-13 (Monday 13th February 2023) and<br>2023-02-19 (Sunday 19th February 2023) inclusive<br> |
| `in` | `due in next week` =><br> due date is on<br>2023-02-17 (Friday 17th February 2023)<br> | `due in next week` =><br> due date is between<br>2023-02-13 (Monday 13th February 2023) and<br>2023-02-19 (Sunday 19th February 2023) inclusive<br> |
| | `due next week` =><br> due date is on<br>2023-02-17 (Friday 17th February 2023)<br> | `due next week` =><br> due date is between<br>2023-02-13 (Monday 13th February 2023) and<br>2023-02-19 (Sunday 19th February 2023) inclusive<br> |
| `after` | `due after next week` =><br> due date is after<br>2023-02-17 (Friday 17th February 2023)<br> | `due after next week` =><br> due date is after<br>2023-02-19 (Sunday 19th February 2023)<br> |

0 comments on commit 34d8eb2

Please sign in to comment.