From 5c762d895796d7e5513234d972b570b4cdcce557 Mon Sep 17 00:00:00 2001 From: epriestley Date: Thu, 25 Jan 2018 10:05:13 -0800 Subject: [PATCH] Document the new "only if this didn't match last time" Herald action setting Summary: Depends on D18930. Ref T13048. Try to explain what this does and give an example since I think it's probably not very obvious from the name. Test Plan: Read the text. Reviewers: amckinley Reviewed By: amckinley Maniphest Tasks: T13048 Differential Revision: https://secure.phabricator.com/D18931 --- src/docs/user/userguide/herald.diviner | 40 +++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/src/docs/user/userguide/herald.diviner b/src/docs/user/userguide/herald.diviner index c5a008474d..b7cfdeca95 100644 --- a/src/docs/user/userguide/herald.diviner +++ b/src/docs/user/userguide/herald.diviner @@ -20,7 +20,7 @@ For example, you can write a personal rule like this which triggers on tasks: > When [ all of ] these conditions are met: > [ Title ][ contains ][ quasar ] -> Take these actions [ every time ] this rule matches: +> Take these actions [ every time this rule matches: ] > [ Add me as a subscriber ] This rule will automatically subscribe you to any newly created or updated @@ -106,6 +106,44 @@ had it actually been updated. Dry runs executed via the test console don't take any actions. +Action Repetition Settings +========================== + +Rules can be configured to act in different ways: + +**Every time the rule matches:** The rule will take actions every time the +object is updated if the rule's conditions match the current object state. + +**Only the first time the rule matches:** The rule will take actions only once +per object, regardless of how many times the object is updated. After the rule +acts once, it won't run on the same object again. + +**If this rule did not match the last time:** This rule will take actions the +first time it matches for an object. After that, it won't act unless the object +just changed from not matching to matching. + +For example, suppose you have a rule like this: + +> When: +> [ Title ][ contains ][ duck ] +> Take actions [ if this rule did not match the last time: ] +> [ Add comment ][ "Please prefer the term 'budget goose'." ] + +If you set this rule to act "every time", it will leave a comment on the task +for every single update until the title is edited. This is usually pretty noisy. + +If you set this rule to act "only the first time", it will only leave one +comment. This fixes the noise problem, but creates a new problem: if someone +edits the title, then a later change breaks it again, the rule won't leave +another reminder comment. + +If you set this rule to act "if it did not match the last time", it will leave +one comment on matching tasks. If the task is fixed (by replacing the term +"duck" with the term "budget goose", so the object no longer matches the rule) +and then later changed to violate the rule again (by putting the term +"duck" back in the title), the rule will act again. + + Advanced Herald ===============