1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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
|
