Git Code Review - an Emacs minor-mode for inline code comments
Introduction
Currently, developer teams use Pull Requests and GitHub’s PR comment system for doing code reviews and discussing the pros and cons of bugfixes and/or feature development. The lifecycle of PRs and their associated comment metadata is too far removed from the code itself and ends up with overall institutional memory loss. Inline Code Comments is an alternative, which proposes keeping review comments inline with the code itself - thereby decoupling the discussion insights from the PR itself.
This Emacs-Lisp package adds a few simple commands to help incorporate inline code comments into a Git workflow, and help make the comments/discussions follow a dead-simple convention.
Each block of comments is called a REVIEW block. A REVIEW block
begins with something like:
;;; REVIEW(author): A one line title (no line break)
;;; Multi-line comment subject, which may incorporate code blocks:
;;;
;;; (defn foo [a]
;;; (do
;;; (complex
;;; (things (with a)))))
;;;
;;; and ends with
;;; ----------------------------------------------------------------Additional comments/replies can be appended using the following convention:
;;; and ends with
;;; ----------------
;;; (second-author): I think the inner call to `complex` can be
;;; refactored using `foo.bar.comple/refactored-implementation`
;;; ----------------------------------------------------------------git-code-review provides commands that make it easy to manage these
review blocks.
Installation
(el-get-bundle kriyative/git-code-review)
(use-package git-code-review
:config
(add-hook 'clojure-mode-hook 'gcr-mode)
(add-hook 'emacs-lisp-mode-hook 'gcr-mode)
(add-hook 'common-lisp-mode-hook 'gcr-mode))Usage
In any code buffer, use the following commands/key bindings
gcr-new-review(C-c R r)
Open the comment editor to create a new REVIEW block
gcr-add-comment(C-c R c)
Open the comment editor and add a comment to an existing REVIEW
block
gcr-edit-comment(C-c R e)
Open the comment editor with the contents of the current comment
gcr-next-review(C-c R n)
Jump to the next REVIEW block
gcr-prev-review(C-c R p)
Jump to the previous REVIEW block
gcr-review-branch
This command can be used to create a local branch of a PR using the remote branch name. After creating the branch, a magit-diff buffer will be opened with the list of changes in the PR.