(feat)capture: rename :if-new template property to :target (#1809)

This name will better reflect the current purpose of the property. At
the beginning of the v2 it would only trigger for the new nodes (hence
:if-new), but through the development it's no longer the case, though
the behavior various from each type of the target.

As for now, this will be soft deprecated and won't be strictly enforced
at the user.

org-roam-compat.el

@@ -153,6 +153,29 @@ nodes." org-id-locations-file)
                            (expand-file-name ".orgids" (file-truename org-roam-directory)))
                      (apply fn args)))))))
 
+(with-eval-after-load 'org-roam-capture
+  ;; :if-new capture template property is deprecated in favor of :target
+  (add-to-list 'org-roam-capture--template-keywords :if-new)
+
+  (advice-add 'org-roam-capture--get-target :around #'org-roam-capture--get-if-new-target-a)
+  (let ((warning-was-displayed 'dont-display)) ; REVIEW Set this to nil close to next major release
+    (defun org-roam-capture--get-if-new-target-a (fn &rest args)
+      "Get the current capture target using deprecated :if-new property."
+      (if-let ((target (org-roam-capture--get :if-new)))
+          (prog1 target
+            (unless warning-was-displayed
+              (lwarn 'org-roam-capture :warning
+                     (mapconcat
+                      #'identity
+                      ["`:if-new' property is deprecated in favor of `:target'."
+                       "This warning will popup once per each session. In order to get"
+                       "rid of it, rename all the references to the `:if-new' property"
+                       "in your capture templates to `:target'."]
+                      "\n"))
+              ;; Don't irritate the user too much. Displaying the warning once per session should be enough.
+              (setq warning-was-displayed t)))
+        (apply fn args)))))
+
 ;;; Obsolete aliases (remove after next major release)
 (define-obsolete-function-alias
   'org-roam-setup