Add eight feature tours with screenshots from a demo repository

README.md

@@ -6,6 +6,8 @@ Built on AvaloniaEdit; editor components adapted from [ILSpy](https://github.com
 
 Siegi and Chris recorded a brief [Introduction to Stampeded!](https://youtu.be/r16YIcvLlg4) for you to get a glimpse at what the IRE is capable of.
 
+To see it at work on a C# repository, take the [feature tours](docs/tour/README.md): eight short walks with screenshots, each under five minutes, that you can follow in a demo repository.
+
 # Motivation
 
 ## What was great in eg gitk, Fork and other tools?

docs/README.md

@@ -16,6 +16,8 @@ Start with [architecture.md](architecture.md). The rest can be read in any order
 
 `CLAUDE.md` in the repository root is the short orientation version of the same material.
 
+What the tool does, as opposed to how it is built, is in the [feature tours](tour/README.md).
+
 ## The shortest possible tour
 
 A review is opened (`ReviewWorkspace.OpenPrAsync`), which fetches the PR head, computes the merge

docs/tour/01-open-and-read.md

@@ -0,0 +1,77 @@
+# Tour 1: Open a pull request and read it
+
+Reading a review here is mostly a keyboard job: file by file, hunk by hunk. This tour takes
+pull request #1 of the demo repository from the start page to the last file.
+
+## 1. The start page
+
+**Review > Open from URL...**, `christophwille/stampeded-demo`.
+
+![The start page: repositories, open pull requests, branches](images/01-01-start-page.png)
+
+Three columns: repositories you've opened recently, the open pull requests with CI state and
+size, and your local branches - each with the pull request it belongs to and whether it still
+matches the remote. Start typing in any list to filter it.
+
+## 2. The overview
+
+Double-click **#1 Price herds by weight class**.
+
+![The overview of pull request #1](images/01-02-overview.png)
+
+This is the review's home tab: a rough reading-time estimate, CI, who has reviewed, the
+linked issue, the description rendered. The Explorer on the left lists the changed files in
+reading order - tests first, since they tell you what the change is supposed to do. Below it
+is the whole repository at the pull request's head, not only the files that changed.
+
+Your clone was not touched to get here. The head sits in a detached worktree in the tool's
+cache; your working tree and index stay as they were.
+
+## 3. The first file
+
+Press `]`.
+
+![A unified diff with word-level changes](images/01-03-first-file.png)
+
+`]` and `[` step through the files. You get both line numbers, the changed words inside a
+changed line, and syntax colours and folding as in an editor. That's not cosmetic: the diff
+really is source code to the tool, which is what tour 2 is about.
+
+## 4. Hunks and viewed flags
+
+`n` and `p` jump between hunks. `v` marks the file viewed and opens the next one - and so does
+`n` once you're past the last hunk.
+
+![Two files ticked off in the Explorer](images/01-04-viewed-and-on.png)
+
+`o` takes you to the overview and back to the file you came from.
+
+## 5. Collapsed context and resolved threads
+
+![Unchanged lines folded into a bar, a resolved thread on one line](images/01-05-context-gap.png)
+
+Unchanged runs collapse into a bar that tells you how many lines it hides. Click it to get
+them back, all at once or twenty at a time. A resolved thread shrinks to a single line until
+you ask for it. The strip along the right edge is the whole file at a glance: red and green
+where it changed, amber where somebody commented.
+
+## 6. Side by side
+
+**View > Side-by-Side Layout**.
+
+![The same file, side by side](images/01-06-side-by-side.png)
+
+Your choice sticks. Either way, a file is one tab.
+
+## 7. Closing and reopening
+
+Quit halfway through and open the pull request again: the files you ticked are still ticked.
+That state is local, keyed by repository and pull request - and it's what tour 5 builds on
+when the author pushes again.
+
+One oddity in this pull request: the author renamed `Pricing.cs` to `PriceCalculator.cs`, but
+you see one file added and one deleted. Over the whole change, too little of the file
+survives for git to call it a rename. [Tour 3](03-commit-by-commit.md) reads the same change
+commit by commit, and there it is one.
+
+Next: [Navigate the code in the diff](02-navigate-the-code.md)

docs/tour/02-navigate-the-code.md

@@ -0,0 +1,78 @@
+# Tour 2: Navigate the code in the diff
+
+A web diff is text. Here, both sides of the diff are compiled: Roslyn loads the solution at
+the pull request's head, plus a second view of it as it was at the merge base. So whatever
+your IDE can tell you about a symbol, the diff can too - on added lines, context lines and
+removed lines alike.
+
+Open pull request #1 of the demo repository and go to `src/Corral/HerdReport.cs`. The
+References pane tells you when the solution has loaded; for the demo that's a few seconds.
+
+## 1. Hover
+
+Rest the pointer on `ClassOf`.
+
+![Quick info for a method, over the diff](images/02-01-hover.png)
+
+Signature, doc comment and null state, same as in the IDE.
+
+## 2. Go to definition
+
+Put the caret on `ClassOf` and press `F12`, or Ctrl+click it.
+
+![The definition, in the file that declares it](images/02-02-definition.png)
+
+If the target file is part of the change you land in its diff, otherwise in plain source.
+`Alt+Left` takes you back, `Alt+Right` forward again.
+
+## 3. Find references
+
+`Shift+F12` on `PriceFor`.
+
+![References, the ones on changed lines marked](images/02-03-references.png)
+
+A `*` marks the references on lines this pull request changes, so you can tell the call sites
+the author touched from the ones that were left alone. Double-click to jump.
+
+## 4. Go to definition from a removed line
+
+One of the removed lines in `HerdReport.cs` calls `pricing.FlatPrice(a)`, a method this pull
+request deletes. Put the caret on it and press `F12`.
+
+![The deleted method, reached from a removed line](images/02-04-removed-code.png)
+
+You land in `Pricing.cs` as it was before the change - a file that doesn't exist at the head
+any more. Hover and find references work there as well, so "what did this do, and who else
+called it?" doesn't mean leaving the review.
+
+## 5. Go to definition in a NuGet package
+
+`F12` on `Humanize`, which comes from the Humanizer package.
+
+![A type from a NuGet package, decompiled](images/02-05-decompiled.png)
+
+No source in the repository, so the type is decompiled and opened read-only.
+
+## 6. Call graph
+
+Caret on `Summarize`, then **Navigate > Call Graph from Caret**.
+
+![The call graph of a changed method](images/02-06-call-graph.png)
+
+Incoming and outgoing calls, expandable level by level. Tick **Only members this review
+changes** to cut the graph down to the part the pull request is actually about.
+
+## 7. Structure and Map
+
+Two more panes share the Explorer's corner. **Structure** is the outline of the file in
+front, with the members the change touches tinted:
+
+![The outline of the file in front](images/02-07-structure.png)
+
+**Map** lists every changed member of the pull request, grouped by file - green for added,
+blue for modified, red for removed. One look tells you this change drops a method, adds an
+enum and rewrites one function, before you've read a line of it:
+
+![Every changed member of the pull request](images/02-08-change-map.png)
+
+Next: [Read it commit by commit](03-commit-by-commit.md)

docs/tour/03-commit-by-commit.md

@@ -0,0 +1,68 @@
+# Tour 3: Read it commit by commit
+
+Some pull requests are a series: each commit one step, meant to be read in order. Pull
+request #1 of the demo repository is four of them, and its description says what each is for.
+
+## 1. Enter the commit scope
+
+**Review > Commit by Commit**, or the first button in the Explorer's toolbar.
+
+![The review narrowed to its first commit](images/03-01-commit-scope.png)
+
+Everything goes purple, so you can't mistake one commit for the whole change. The Explorer
+shows the commit message and only the files that commit touched, and the overview is
+recomputed for it.
+
+## 2. The rename, as a rename
+
+Open `PriceCalculator.cs`.
+
+![The first commit: a rename and one changed line](images/03-02-rename.png)
+
+In the whole change this file looked brand new (tour 1). In the commit that renamed it, it's
+an `R` and a single changed line.
+
+## 3. Step through the commits
+
+`Ctrl+]` goes to the next commit, `Ctrl+[` to the previous one.
+
+![The second commit](images/03-03-next-commit.png)
+
+Viewed flags are kept per commit, so `v` works the way it does in the whole change. Comments
+belong to the pull request: the thread on line 13 shows up in the commit that wrote that
+line.
+
+**Review > Whole Change** gets you out again. Try to approve with part of the series unread
+and you'll be told so instead.
+
+## 4. The Commits pane
+
+Back in the whole change, open **Commits**.
+
+![Commits of the review, the files of one, its message](images/03-04-commits-pane.png)
+
+Select a commit to see its files and full message. Double-click a file to see what that one
+commit did to it, without switching scope.
+
+## 5. Blame
+
+Press `b`.
+
+![The blame margin on a diff](images/03-05-blame.png)
+
+Both sides get blamed: a removed line shows the commit that originally wrote it, an added
+line the commit of this pull request that added it. The margin is tinted by age, so the lines
+this pull request wrote stand out from the ones it inherited.
+
+## 6. File history
+
+The **History** pane follows whatever file is in front.
+
+![The history of the file in front](images/03-06-history.png)
+
+It lists the commits that touched the file on the branch your clone has checked out - in
+other words, where the file was before this change. Double-click a commit for its diff.
+**Navigate > History of Selection** searches the same history for the commits that added or
+removed the text you've selected.
+
+Next: [Comment and submit](04-comment-and-submit.md)

docs/tour/04-comment-and-submit.md

@@ -0,0 +1,74 @@
+# Tour 4: Comment and submit
+
+You write comments right where the code is, and they stay on your machine until you submit.
+The author gets one review, not a drip of notifications.
+
+Open pull request #1 of the demo repository and go to `src/Corral/PriceCalculator.cs`.
+
+## 1. Existing threads
+
+![A posted thread between the lines it is about](images/04-01-thread.png)
+
+Threads from the host sit in the diff, under the line they're about, with Reply and Resolve
+right there. The Explorer shows a count per file: amber while something is still open, green
+once it's all settled.
+
+## 2. Comment at the caret
+
+Put the caret on a line and press `c`.
+
+![The comment editor on a line](images/04-02-comment-editor.png)
+
+`Ctrl+Enter` saves, `Esc` closes. Once you've typed something, clicking into the code behind
+the editor won't dismiss it and take your text with it.
+
+## 3. Drafts
+
+![The draft, in place](images/04-03-draft.png)
+
+The draft sits where it will be posted, with Edit and Delete on it, and it's still there
+after you close the app.
+
+## 4. Suggest a change
+
+`c` on another line, then **Suggest a change**. The editor is prefilled with a suggestion
+block holding that line, ready for you to rewrite.
+
+![A suggestion being written](images/04-04-suggestion.png)
+
+On GitHub the author can commit a suggestion with one click. Azure DevOps has no such thing,
+so there it posts as a plain code block.
+
+## 5. Reply
+
+Click **Reply** on the posted thread.
+
+![A reply and a suggestion, both drafts](images/04-05-reply.png)
+
+Replies are drafts too.
+
+## 6. The Comments pane and the review page
+
+The **Comments** pane lists every draft and posted comment of the review. Double-click one to
+go to it.
+
+![The Comments pane](images/04-06-comments-pane.png)
+
+**Review > Approve / Request Changes...** opens the review page: each comment quoted with the
+code around it, the way the author will see it. The summary goes in the box at the bottom.
+
+![The review page before submitting](images/04-07-review.png)
+
+## 7. Submit
+
+![The review after submitting](images/04-08-submitted.png)
+
+**Comment** posts the three drafts as one review. **Approve** and **Request Changes** are
+greyed out in this picture because it was taken by the pull request's own author, and GitHub
+doesn't accept either verdict from the author. On somebody else's pull request they're live.
+
+If a draft sits on a line the host would reject - outside the diff, or in a generated file -
+it's kept as a local draft instead of sinking the whole review, and the result line tells you
+how many were.
+
+Next: [Come back after a force push](05-after-a-force-push.md)

docs/tour/05-after-a-force-push.md

@@ -0,0 +1,57 @@
+# Tour 5: Come back after a force push
+
+You've read a pull request. Then the author rebases onto a newer `main`, amends a commit and
+force-pushes. On the web you're more or less starting over: the commits you read are gone,
+and "changes since your last review" is either unavailable or full of other people's work
+that came along with the rebase.
+
+This tour needs a push, so you can't follow it in the shared demo repository. Fork it and run
+its `stage.ps1` if you want to try it yourself.
+
+## 1. The first pass
+
+Pull request #2, every file ticked off with `v`. There's one thread, on line 29 of `Herd.cs`.
+
+![The first pass: all files viewed, a comment on line 29](images/05-01-first-pass.png)
+
+## 2. The push
+
+The author rebases onto `main` (which gained a commit in the meantime), moves `IsValidBrand`
+to the end of its file and adds a third commit. `stage.ps1 -Push2` does exactly that.
+
+Reload with `F5`, or simply open the pull request again.
+
+![After the push: two files still ticked, the rest marked new](images/05-02-after-the-push.png)
+
+The two files that read the same as before are still ticked. The other six are unticked
+again - you did read them, just not as they are now - and `new!` flags a file that changed
+since you did.
+
+## 3. Since your last pass
+
+**Review > Since Last Pass**.
+
+![Only what the author changed since the first reading](images/05-03-since-last-pass.png)
+
+Three files instead of eight, and in them only what the author actually edited. Whatever
+`main` brought in through the rebase is not in this diff, even though it is part of the
+difference between the two pushes.
+
+The trick: this isn't old head against new head. The work you already read is replayed onto
+the new base as a tree, and the new head is diffed against that. The window stays orange for
+as long as you're in this scope.
+
+**Review > Last Pass Was** lets you pick what counts as your last pass: the last file you
+ticked off (the default, because opening a review isn't the same as reading it), your last
+submitted review, or the last time you opened it.
+
+## 4. Comments after the push
+
+![The thread, now on line 38](images/05-04-moved-comment.png)
+
+The thread was written against line 29 of a commit that's no longer on the branch. It now
+sits on line 38: same statement, in the method that moved. When the host can no longer say
+which line a comment belongs to, the line is found again by its content - and if that fails,
+by the member it was written in.
+
+Next: [CI, tests and coverage](06-ci-tests-coverage.md)