#+TITLE: org-review

Track when you have done a review in org mode.

Tasks typically have Scheduled and Deadline time stamps, which define when the task has to be done. Org-review lets you attach an additional review time stamp to a task, which can be used to schedule a review of the task.

* Installation

*TLDR* This is what I use in my [[https://github.com/progfolio/elpaca][elpaca]] configuration.
#+begin_src emacs-lisp
  (use-package org-review
    :ensure (:fetcher github :repo "brabalan/org-review")
    :bind (:map org-agenda-mode-map
                ("C-c C-r" . org-review-insert-last-review)))
#+end_src

1. Copy ~org-review.el~ to a path known to emacs and add the following to your emacs configuration file.
   #+begin_src emacs-lisp
     (require 'org-review)
   #+end_src
2. Configure an agenda view that shows the projects that are available for review. You could for instance add the following in your emacs configuration file.
   #+begin_src emacs-lisp
     (setq org-agenda-custom-commands
           '(("R" "Review projects" tags-todo "-CANCELLED/"
              ((org-agenda-overriding-header "Reviews Scheduled")
               (org-agenda-skip-function 'org-review-agenda-skip)
               (org-agenda-cmp-user-defined 'org-review-compare)
               (org-agenda-sorting-strategy '(user-defined-down))))))
   #+end_src
3. If you want to mark a project reviewed when you are in an agenda view, you can do so by assigning a key binding for the ~org-review-insert-last-review~ function.
   #+begin_src emacs-lisp
     (add-hook 'org-agenda-mode-hook
               (lambda ()
                 (local-set-key (kbd "C-c C-r")
                                'org-review-insert-last-review)))
   #+end_src

* How it works

Entries will be scheduled for review if their ~NEXT_REVIEW~ or
their ~LAST_REVIEW~ property is set. The next review date is
the ~NEXT_REVIEW~ date, if it is present, otherwise it is computed
from the ~LAST_REVIEW~ property and the ~REVIEW_DELAY~ period, such
as ~+1m~. If ~REVIEW_DELAY~ is absent, a default period is used. Note
that the ~LAST_REVIEW~ property is not considered as inherited,
but ~REVIEW_DELAY~ is, allowing to set it for whole subtrees.

To set these properties, you may use the ~org-set-property~ command
(bound to ~C-c C-x p~ by default). For the ~NEXT_REVIEW~ property,
a command ~org-review-insert-next-review~ is provided, that prompts
for a date and inserts it.

Checking of review dates is done through an agenda view, using
the ~org-review-agenda-skip~ skipping function. This function is based
on ~org-review-toreview-p~, that returns ~nil~ if no review is
necessary (no review planned or it happened recently), otherwise it
returns the date the review was first necessary (~NEXT_REVIEW~,
or ~LAST_REVIEW + REVIEW_DELAY~, if it is in the past).

To mark an entry as reviewed, use the
function ~org-review-insert-last-review~ to set the ~LAST_REVIEW~ date
to the current date. If ~org-review-sets-next-date~ is set (which is
the default), this function also computes the date of the next review
and inserts it as ~NEXT_REVIEW~.

Several options, such as the format of the time stamps, may be set
using the ~customize-group~ command for the ~org-review~ group.