Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs fix: dates in Recurring Tasks examples #2601

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

st--
Copy link
Contributor

@st-- st-- commented Jan 19, 2024

Description

I've changed some of the dates in the examples to make them self-consistent.
I've also added the "assumed date" in one example to make it more immediately understandable.

Motivation and Context

It took me a bit longer to figure out how the recurrence relations work because the examples were a bit confusing to me.

Types of changes

Changes visible to users:

  • Bug fix (prefix: fix - non-breaking change which fixes an issue)
  • New feature (prefix: feat - non-breaking change which adds functionality)
  • Breaking change (prefix: feat!! or fix!! - fix or feature that would cause existing functionality to not work as expected)
  • Documentation (prefix: docs - improvements to any documentation content for users)
  • Sample vault (prefix: vault - improvements to the Tasks-Demo sample vault)
  • Contributing Guidelines (prefix: contrib - any improvements to documentation content for contributors - see Contributing to Tasks)

Internal changes:

  • Refactor (prefix: refactor - non-breaking change which only improves the design or structure of existing code, and making no changes to its external behaviour)
  • Tests (prefix: test - additions and improvements to unit tests and the smoke tests)
  • Infrastructure (prefix: chore - examples include GitHub Actions, issue templates)

Checklist

Terms

@claremacrae
Copy link
Collaborator

Hi @st--

Thank you. Could you describe the changes you actually made please? What was wrong with the old dates and so how did you chose the new ones?

@st--
Copy link
Contributor Author

st-- commented Jan 19, 2024

Could you describe the changes you actually made please? What was wrong with the old dates and so how did you chose the new ones?

In some of the examples, the years weren't consistent throughout the example. Maybe this was due to features being added later?

E.g.
https://github.com/obsidian-tasks-group/obsidian-tasks/pull/2601/files#diff-0da6c703d3753dedf34b4c78484d29231f2e9c2173f8e3bdfb6edf2aede66e9bR41-R44

-- [ ] take out the trash 🔁 every Sunday ➕ 2023-03-10 📅 2021-05-02
-- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2023-03-10
+- [ ] take out the trash 🔁 every Sunday ➕ 2021-04-24 📅 2021-05-02
+- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2021-04-24

Previously, it jumped to 2023 for the "marked complete"/"created" date even though the "due date" was living in 2021

@st--
Copy link
Contributor Author

st-- commented Jan 19, 2024

9e156fd#diff-7180dda3f3ee0ae61f9611e70893a879113dfb5d175cc4cce691ecc3b940ced4 was committed on 2023-03-10

and adds the following example:

- [ ] take out the trash 🔁 every Sunday ➕ 2023-03-10 📅 2021-05-02
- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2023-03-10

which uses the commit date for the newly added functionality (completed date of previous occurrence -> created date of new occurrence) but kept the due date from before, which I found rather confusing. So I've just "backdated" the newly added dates in examples.

@claremacrae
Copy link
Collaborator

Super. Thanks for the replies.

@claremacrae
Copy link
Collaborator

Could you describe the changes you actually made please? What was wrong with the old dates and so how did you chose the new ones?

In some of the examples, the years weren't consistent throughout the example. Maybe this was due to features being added later?

E.g. https://github.com/obsidian-tasks-group/obsidian-tasks/pull/2601/files#diff-0da6c703d3753dedf34b4c78484d29231f2e9c2173f8e3bdfb6edf2aede66e9bR41-R44

-- [ ] take out the trash 🔁 every Sunday ➕ 2023-03-10 📅 2021-05-02
-- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2023-03-10
+- [ ] take out the trash 🔁 every Sunday ➕ 2021-04-24 📅 2021-05-02
+- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2021-04-24

Previously, it jumped to 2023 for the "marked complete"/"created" date even though the "due date" was living in 2021

I think the years were not consistent because it was trying to make the point that however late you complete a task that does not have when done, the new date is calculated from the previous due date.

@st--
Copy link
Contributor Author

st-- commented Jan 24, 2024

I think the years were not consistent because it was trying to make the point that however late you complete a task that does not have when done, the new date is calculated from the previous due date.

I don't think so - the part where the year had jumped to 2023 only addresses whether a creation date is added when completing a recurrence.
The documentation of when done vs default is further below (where there were also some inconsistencies that I removed), and has explicit discussion of the dates in the surrounding text that also make me believe my changes are how it ought to be (given the surrounding explanation).

Comment on lines -42 to +43
- [ ] take out the trash 🔁 every Sunday ➕ 2023-03-10 📅 2021-05-02
- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2023-03-10
- [ ] take out the trash 🔁 every Sunday ➕ 2021-04-24 📅 2021-05-02
- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2021-04-24
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the documentation of the "addition of created dates" feature, so I believe it should be consistent with the previous example (lines 33-34) that has completion marked in 2021

Comment on lines -68 to +69
- [ ] sweep the floors 🔁 every week ⏳ 2021-02-13
- [x] sweep the floors 🔁 every week ⏳ 2021-02-06 ✅ 2022-02-13
- [ ] sweep the floors 🔁 every week ⏳ 2022-02-13
- [x] sweep the floors 🔁 every week ⏳ 2022-02-06 ✅ 2022-02-13
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As noted by the surrounding text, the completion should be one week after the originally scheduled date (not one week and a year), and the scheduled date of the new task should be the same as the completed date of the previous occurrence

- [x] sweep the floors 🔁 every week when done ⏳ 2021-02-06 ✅ 2022-02-13
- [x] sweep the floors 🔁 every week when done ⏳ 2022-02-06 ✅ 2022-02-13
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as previous change; here the difference of including the when done is that the next scheduled date is February 20 (one week after completed date) rather than February 13 (one week after original scheduled date), but the year should still be the same.

@claremacrae
Copy link
Collaborator

Setting to draft status any PRs which are not currently mergable, but will be useful in future.

I want to write some tests to confirm these changes, and ideally machine-generate the recurring tasks examples.

@claremacrae claremacrae marked this pull request as draft May 7, 2024 19:36
@claremacrae claremacrae added the scope: documentation Improvements or additions to documentation label May 12, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
scope: documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants