Merge pull request #3485 from obsidian-tasks-group/feat-presets

feat!!: Rename 'include' facility to 'preset'

Author: claremacrae

contributing/Architecture Decisions/ADR-001 - Nomenclature for Reusable Instruction Blocks Feature.md

@@ -0,0 +1,92 @@
+---
+publish: true
+---
+
+# ADR-001 - Nomenclature for Reusable Instruction Blocks Feature
+
+## Status
+
+**ACCEPTED** - Decision made on 2025-05-29
+
+## Context
+
+The Tasks plugin introduced a feature allowing users to define reusable blocks of Tasks instructions in settings and reference them in queries. This feature was initially named "Includes" with the following syntax:
+
+- Direct instruction: `include standard_options`  
+- Placeholder syntax: `{{includes.standard_options}}`
+
+However, during pre-release testing, a significant naming collision was identified with the existing text search functionality:
+
+- Existing: `description includes blah` (searches for text containing "blah")
+- New feature: `include standard_options` (imports predefined instruction block)
+
+This collision creates cognitive overhead and potential user confusion, necessitating a nomenclature change before public release.
+
+## Decision
+
+We will rename the feature from "Includes" to "Presets" with the following syntax:
+
+- **Direct instruction:** `preset standard_options`
+- **Placeholder syntax:** `{{preset.standard_options}}` (singular for consistency)
+
+## Alternatives Considered
+
+The following alternatives were evaluated in priority order:
+
+| Priority | Direct Syntax                 | Placeholder Syntax                 | Assessment                                      |
+| -------- | ----------------------------- | ---------------------------------- | ----------------------------------------------- |
+| **1**    | `preset standard_options`     | `{{presets.standard_options}}`     | ✅ No conflicts, user-friendly                  |
+| 2        | `macro standard_options`      | `{{macros.standard_options}}`      | ✅ No conflicts, technical precision            |
+| 3        | `def standard_options`        | `{{defs.standard_options}}`        | ✅ No conflicts, programming-friendly           |
+| 4        | `definition standard_options` | `{{definitions.standard_options}}` | ✅ No conflicts, verbose                        |
+| 5        | `import standard_options`     | `{{imports.standard_options}}`     | ✅ No conflicts, developer-oriented             |
+| 6        | `block standard_options`      | `{{blocks.standard_options}}`      | ⚠️ Potential confusion with Obsidian block refs |
+| 7        | `reference standard_options`  | `{{references.standard_options}}`  | ⚠️ Potential confusion with Obsidian links      |
+| 8        | `ref standard_options`        | `{{refs.standard_options}}`        | ⚠️ Potential confusion with Obsidian links      |
+| 9        | `include standard_options`    | `{{includes.standard_options}}`    | ❌ Conflicts with `description includes text`   |
+| 10       | `snippet standard_options`    | `{{snippets.standard_options}}`    | ❌ Conflicts with Obsidian CSS snippets         |
+| 11       | `template standard_options`   | `{{templates.standard_options}}`   | ❌ Strong conflict with Obsidian Templates      |
+
+## Rationale
+
+"Preset" was selected as the optimal choice because:
+
+1. **Zero Conflicts:** No collision with existing Tasks functionality or Obsidian features
+2. **User Accessibility:** Least programmer-centric terminology among viable options
+3. **Familiar Concept:** Widely used across many software applications (camera presets, filter presets, etc.)
+4. **Clear Intent:** Immediately conveys the concept of predefined configurations
+5. **Broad Appeal:** Accessible to users across all technical levels
+
+The decision to use singular form in placeholder syntax (`{{preset.name}}` instead of `{{presets.name}}`) maintains consistency with other Tasks placeholder patterns.
+
+## Consequences
+
+### Positive
+
+- Eliminates user confusion from naming collision
+- Provides clear, accessible terminology
+- Maintains feature functionality while improving usability
+- Establishes consistent naming pattern for future features
+
+### Negative
+
+- Requires updating developer's own test configurations (feature is pre-release)
+- Documentation and examples need updating before public release
+
+### Neutral
+
+- No user impact since feature is unreleased
+- Error messages and validation logic require updates
+
+## Implementation Notes
+
+- Update all pre-release documentation and examples to use new terminology
+- No user migration needed since feature is unreleased
+- Error messages and validation logic should use "preset" terminology
+- Release feature publicly with "preset" nomenclature
+
+---
+
+**Decision made by:** Clare Macrae
+**Date:** 2025-05-29  
+**ADR Number:** 001

contributing/Architecture Decisions/About Architecture Decisions.md

@@ -0,0 +1,13 @@
+---
+publish: true
+---
+
+# About Architecture Decisions
+
+## Introduction
+
+This a collection of [Architecture decision records (ADRs)](https://github.com/joelparkerhenderson/architecture-decision-record) for the Tasks plugin.
+
+If a design decision was non-obvious, we will record the thought process here.
+
+- [[ADR-001 - Nomenclature for Reusable Instruction Blocks Feature]]

contributing/Welcome.md

@@ -20,6 +20,7 @@ Getting the most from this documentation:
 - See [[About Testing]] to learn about automated and manual testing of the plugin
 - See [[About Debugging]] for tips to debug the plugin
 - See [[About Code]] for descriptions of the project's source code
+- See [[About Architecture Decisions]] for Architecture Decision Records
 - See [[About Documentation]] if you would like to improve and test the user docs
 - See [[About Translation]] if you are adding new text the plugin, and to help translate it
 

docs/Scripting/Placeholders.md

@@ -75,15 +75,15 @@ Explanation of this Tasks code block query:
 
 It is now possible to use properties in the query file. See [[Obsidian Properties#Using Query Properties in Searches]]
 
-## Using includes.xxx
+## Using preset.xxx
 
 You can do the following:
 
 ```text
-{{includes.my_snippet_from_settings}}
+{{preset.my_snippet_from_settings}}
 ```
 
-See also [[Includes]].
+See also [[Presets]].
 
 ## Error checking: invalid variables
 

docs/Scripting/Includes.md renamed to docs/Scripting/Presets.md

@@ -2,12 +2,12 @@
 publish: true
 ---
 
-# Includes
+# Presets
 
 <span class="related-pages">#feature/scripting</span>
 
 ```text
-include my_snippet_from_settings
+preset my_snippet_from_settings
 ```
 
 You can only include full lines (valid instructions).

resources/sample_vaults/Tasks-Demo/.obsidian/plugins/obsidian-tasks-plugin/data.json

@@ -1,10 +1,10 @@
 {
-  "includes": {
+  "presets": {
     "hide_all_dates": "# Hide any values for all 6 date fields\nhide due date\nhide scheduled date\nhide start date\nhide created date\nhide done date\nhide cancelled date",
     "hide_buttons": "# Hide postpone, edit and backinks\nhide postpone button\nhide edit button\nhide backlinks",
     "hide_other_fields": "# Hide all the non-date fields, keep tags\nhide id\nhide depends on\nhide recurrence rule\nhide on completion\nhide priority",
-    "just_the_description_and_tags": "# Show only description and any tags\ninclude hide_all_dates\ninclude hide_other_fields\ninclude hide_buttons",
-    "just_the_description": "# Show only description, not even the tags\ninclude just_the_description_and_tags\nhide tags",
+    "just_the_description_and_tags": "# Show only description and any tags\npreset hide_all_dates\npreset hide_other_fields\npreset hide_buttons",
+    "just_the_description": "# Show only description, not even the tags\npreset just_the_description_and_tags\nhide tags",
     "filter_by_context": "filter by function let fn = (ctx) => task.tags.includes(`#context/${ctx}`); return fn",
     "extract_contexts_1": "ctx => task.tags.includes(`#context/${ctx}`)",
     "extract_contexts_2": "(ctx => task.tags.includes(`#context/${ctx}`))"

resources/sample_vaults/Tasks-Demo/How To/Reuse instructions across the vault.md

@@ -9,7 +9,7 @@ TQ_extra_instructions: |-
 
 These searches are for experimenting with, and understanding, the new "Includes" facility, which was released in Tasks X.Y.Z.
 
-Includes values can be defined in the Tasks settings.
+presets values can be defined in the Tasks settings.
 
 explain: `INPUT[toggle:TQ_explain]`
 
@@ -19,12 +19,12 @@ explain: `INPUT[toggle:TQ_explain]`
 
 ````text
 ```tasks
-include xxxx
+preset xxxx
 ```
 ````
 
 ```tasks
-include xxxx
+preset xxxx
 ```
 
 ## Show all the fields
@@ -45,14 +45,14 @@ explain: `INPUT[toggle:TQ_explain]`
 
 ````text
 ```tasks
-include hide_all_dates
-include hide_other_fields
+preset hide_all_dates
+preset hide_other_fields
 ```
 ````
 
 ```tasks
-include hide_all_dates
-include hide_other_fields
+preset hide_all_dates
+preset hide_other_fields
 ```
 
 ## Hide all the Tasks user interface elements
@@ -61,12 +61,12 @@ explain: `INPUT[toggle:TQ_explain]`
 
 ````text
 ```tasks
-include hide_buttons
+preset hide_buttons
 ```
 ````
 
 ```tasks
-include hide_buttons
+preset hide_buttons
 ```
 
 ## Show only the description and any tags
@@ -75,12 +75,12 @@ explain: `INPUT[toggle:TQ_explain]`
 
 ````text
 ```tasks
-include just_the_description_and_tags
+preset just_the_description_and_tags
 ```
 ````
 
 ```tasks
-include just_the_description_and_tags
+preset just_the_description_and_tags
 ```
 
 ## Just show the description, without tags
@@ -89,12 +89,12 @@ explain: `INPUT[toggle:TQ_explain]`
 
 ````text
 ```tasks
-include just_the_description
+preset just_the_description
 ```
 ````
 
 ```tasks
-include just_the_description
+preset just_the_description
 ```
 
 ## Advanced use: return a function, that takes a parameter from the query source
@@ -106,17 +106,17 @@ explain: `INPUT[toggle:TQ_explain]`
 ````text
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
-group by function const x = "{{includes.filter_by_context}}"; return x
+group by function const x = "{{preset.filter_by_context}}"; return x
 
-{{includes.filter_by_context}}('home')
+{{preset.filter_by_context}}('home')
 ```
 ````
 
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
-group by function const x = "{{includes.filter_by_context}}"; return x
+group by function const x = "{{preset.filter_by_context}}"; return x
 
-{{includes.filter_by_context}}('home')
+{{preset.filter_by_context}}('home')
 ```
 
 ### Has context 'home' - and group by the Include text - version 2
@@ -126,19 +126,19 @@ explain: `INPUT[toggle:TQ_explain]`
 ````text
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
-group by function const x = "{{includes.extract_contexts_1}}"; return x
+group by function const x = "{{preset.extract_contexts_1}}"; return x
 
 # includes.extract_contexts_1 value needs to be surrounded by parentheses ():
-filter by function return ({{includes.extract_contexts_1}})('home')
+filter by function return ({{preset.extract_contexts_1}})('home')
 ```
 ````
 
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
-group by function const x = "{{includes.extract_contexts_1}}"; return x
+group by function const x = "{{preset.extract_contexts_1}}"; return x
 
 # includes.extract_contexts_1 value needs to be surrounded by parentheses ():
-filter by function return ({{includes.extract_contexts_1}})('home')
+filter by function return ({{preset.extract_contexts_1}})('home')
 ```
 
 ### Has context 'home' - and group by the Include text - version 3
@@ -148,17 +148,17 @@ explain: `INPUT[toggle:TQ_explain]`
 ````text
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
-group by function const x = "{{includes.extract_contexts_2}}"; return x
+group by function const x = "{{preset.extract_contexts_2}}"; return x
 
 # includes.extract_contexts_1 value has the parentheses, to simplify use:
-filter by function {{includes.extract_contexts_2}}('home')
+filter by function {{preset.extract_contexts_2}}('home')
 ```
 ````
 
 ```tasks
 # For debug/explanatory purposes, show the source of the Include as a group name:
-group by function const x = "{{includes.extract_contexts_2}}"; return x
+group by function const x = "{{preset.extract_contexts_2}}"; return x
 
 # includes.extract_contexts_1 value has the parentheses, to simplify use:
-filter by function {{includes.extract_contexts_2}}('home')
+filter by function {{preset.extract_contexts_2}}('home')
 ```

src/Config/IncludesSettingsUI.ts

@@ -41,7 +41,7 @@ export class IncludesSettingsUI {
             // Clear the input map when re-rendering
             this.nameFields.clear();
 
-            Object.entries(settings.includes).forEach(([key, value]) => {
+            Object.entries(settings.presets).forEach(([key, value]) => {
                 this.renderIncludeItem(includesContainer, settings, key, value, renderIncludes);
             });
         };
@@ -94,7 +94,7 @@ export class IncludesSettingsUI {
             // Handle renaming an include
             const commitRename = async () => {
                 if (newKey && newKey !== key) {
-                    const updatedIncludes = this.includesSettingsService.renameInclude(settings.includes, key, newKey);
+                    const updatedIncludes = this.includesSettingsService.renameInclude(settings.presets, key, newKey);
                     if (updatedIncludes) {
                         await this.saveIncludesSettings(updatedIncludes, settings, refreshView);
                     }
@@ -119,7 +119,7 @@ export class IncludesSettingsUI {
 
             return textArea.onChange(async (newValue) => {
                 const updatedIncludes = this.includesSettingsService.updateIncludeValue(
-                    settings.includes,
+                    settings.presets,
                     key,
                     newValue,
                 );
@@ -147,7 +147,7 @@ export class IncludesSettingsUI {
             btn.setIcon('cross')
                 .setTooltip('Delete')
                 .onClick(async () => {
-                    const updatedIncludes = this.includesSettingsService.deleteInclude(settings.includes, key);
+                    const updatedIncludes = this.includesSettingsService.deleteInclude(settings.presets, key);
                     await this.saveIncludesSettings(updatedIncludes, settings, refreshView);
                 });
         });
@@ -225,7 +225,7 @@ export class IncludesSettingsUI {
 
             // Perform the reorder
             const updatedIncludes = this.includesSettingsService.reorderInclude(
-                settings.includes,
+                settings.presets,
                 draggedKey,
                 targetIndex,
             );
@@ -246,7 +246,7 @@ export class IncludesSettingsUI {
      */
     private getTargetIndex(targetKey: string, position: 'above' | 'below'): number {
         const settings = getSettings();
-        const keys = Object.keys(settings.includes);
+        const keys = Object.keys(settings.presets);
         const targetIndex = keys.indexOf(targetKey);
 
         if (position === 'above') {
@@ -361,7 +361,7 @@ export class IncludesSettingsUI {
             btn.setButtonText('Add new include')
                 .setCta()
                 .onClick(async () => {
-                    const { includes: updatedIncludes } = this.includesSettingsService.addInclude(settings.includes);
+                    const { includes: updatedIncludes } = this.includesSettingsService.addInclude(settings.presets);
                     await this.saveIncludesSettings(updatedIncludes, settings, refreshView);
                 });
         });
@@ -380,11 +380,11 @@ export class IncludesSettingsUI {
     ) {
         // TODO Consider how this relates to the validation code - should it refuse to save settings if validation fails?
         // Update the settings in storage
-        updateSettings({ includes: updatedIncludes });
+        updateSettings({ presets: updatedIncludes });
         await this.plugin.saveSettings();
 
         // Update the local settings object to reflect the changes
-        settings.includes = { ...updatedIncludes };
+        settings.presets = { ...updatedIncludes };
 
         // Refresh the view if a callback was provided
         if (refreshView) {