add REVIEWING.md

1 files changed, 80 insertions, 0 deletions

diff --git a/REVIEWING.md b/REVIEWING.md
new file mode 100644
index 0000000..6c115b2
--- /dev/null
+++ b/REVIEWING.md
@@ -0,0 +1,80 @@
+# Reviews using anissue
+
+## Performing an initial review
+
+In order to review a feature, a co-author has created a feature branch, which can be merged into `main`. Say that feature branch is called `feature/a`.
+
+```console
+anissue review feature/a
+```
+
+This command will check out `origin/feature/a` and present you with `git diff origin/main origin/feature/a`'s output in our `$EDITOR`.
+
+You are free to add arbitrary text into the diff, without prefixing lines with `+`, `-` or block- or line-comments.
+
+Any additions made to the diff will eventually be turned into a commit on top of `feature/a`, adding your comments.
+
+The comments you've added will be eventually added as comments to the source code.
+
+During reviewing, you are free to write and close your editor to further examine the code base. You can continue where you've picked off by calling `anissue review --continue`, which will again present you with your most revent view in your `$EDITOR`.
+
+To finalize your review, you just push your single reviewing commit to `origin/feature/a`.
+
+## Working through a review
+
+After the initial review, there are likely `COMMENT` marked comments in your source tree. You, as the author, may call
+
+```
+anissue review feature/a
+```
+
+to continue elaborating on the review. At any point, you are free to make additional commits, and continue calling
+
+```
+anissue review feature/a
+```
+
+to finalize your action. You action is published by pushing all new commits to `origin/feature/a`.
+
+In this mode, `anissue review` works differently. It detects that a review is ongoing by the presence of at least one `COMMENT`-marked comment.
+
+The command will then interactively present you each `COMMENT`-marked comment, and you have the following options.
+
+```console
+[e] reply [r] resolve [s] skip
+```
+
+Chosing `[e] reply` will open your `$EDITOR` with the diff of the origin comment shown. You may add arbitrary lines drafting your reply.
+
+Those lines will get added as a commit adding your reply as another `COMMENT`-marked block directly below the original comment-marked block.
+
+Chosing `[r] resolve` will do the same, except that the added block will be marked `RESOLVED` instead of comment.
+
+Chosing `[s] skip` will prompt for the next comment block or terminate `anissue review`.
+
+## Finishing a review
+
+You may enter `anissue merge` to merge `feature/a` into `main`.
+
+This command presents the additional verification that all `COMMENT`-marked streams of conversation end with a `RESOLVED`-marked comment block.
+
+A final commit is being created deleting all `COMMENT`- or `RESOLVED`-marked comment blocks from `feature/a`, and the branch is merged.
+
+## Implementation Details
+
+Whenever a `COMMENT`-marked comment is presented, all `COMMENT`-marked streams are presented if there are multiple consecutive `COMMENT`- or `RESOLVED`-marked comments.
+
+Currently, we are only able to review feature branches as a whole. We will leave reviewing individual commits of branches consisting of more than one commit for a later iteration.
+
+Also left for a later iteration, `anissue review` could record seen comment streams in a file `.anissue/seen/feature/a` to only show new (or changed) comments regarding its last invocation.
+
+`RESOLVED`-marked streams, *can* be commented upon, essentially unresolving a comment stream. A comment stream is resolved if the last comment is a `RESOLVED`-marked comment.
+
+Approval of changes are for the moment not handled.
+
+While, through `anissue merge`, no `COMMENT`-marked comments are present in `HEAD`, the whole reviewing history is preserved within commits in the Git history. This may or may not change in the future.
+
+Technically, we have to solve the following issues:
+
+- interleaving diffs with additional lines, which have to get turned into additions (should be easy, just mark them with `+`)
+- given two diffs, the original diff, and the diff with comments, we have to extract a diff that only contains the comments. This is probably fairly easy to solve creating a new temporary commit with all the changes, comments included, and diff that with the original branch, generating a diff only adding comments