In 2017 Week 20, we've shipped a number of changes to inline comments in Differential and Diffusion.
Most of these changes were aimed at refactoring the code to support future feature development and fixing obscure bugs which most users are unlikely to encounter. Features should start landing in the coming week, and we'll do more of a "feature announcement" writeup in 2-3 weeks once this stuff feels stable. However, some visible things have already changed:
Persistent Header: While reviewing changes, there is a new persistent header which shows which file you're currently looking at (see D17957 for a screenshot). We originally had a similar header in 2012, but temporarily removed it for a brief period of 5 years. I currently intend to add more features to this header unless we get substantial feedback that it is loathed.
Scrollbar Annotations: A new element provides icon annotations near the scrollbar, showing where in the document changes and inlines are and allowing you to quickly jump to specific points of interest. The major goal goal of this change is to make it easer to keep track of things like this:
- "Done" () vs "un-done" () inlines. If you like checking off every inline, you can now tell at a glance if you're missing any.
- Comments from older versions of a change () vs comments on the current diff ().
- Draft comments you've made () vs comments others have made.
- Comments you're currently writing ().
- Generally, to provide a better spatial UI for navigating changes.
This is currently fairly rough and may or may not stick. If you like it / hate it, feedback could help us figure out whether to keep it, change it, or get rid of it.
Multiple Edit/Undo: Previously, edit/undo state was global and you could not edit more than one comment at a time. Each comment can now be edited independently. This is good and bad (see below).
Hide vs Collapse: The "hide" behavior, which folded groups of comments completely into the sidebar, is now a less aggressive "collapse" behavior which reduces comments to a single line. I expect future changes connected to T8909 to add a way to completely hide things. This was largely aimed at fixing a lot of bugs which were hard to tackle with the old approach, and at making keyboard navigation more consistent and predictable.
Key Command Changes: Some changes have been made to keyboard commands:
- r can now reply to changes, not just comments.
- R can now reply to comments, quoting the comment.
- w can now mark changes "done" (or remove the mark).
- q can now toggle the visibility of changes.
- Click-to-select: Clicking the header of an inline or the scrollbar annotation for that inline now selects it with the keyboard focus reticle. You can click again to deselect it.
- The reticle should now do a better job of remembering your position in the document when you make edits.
Known / Suspected Issues
Undo Clutter: If you, e.g., create and then cancel a lot of inlines you can end up with a lot of "Undo" clutter. Previously, each "undo" wiped out existing undo state. I currently plan to make this use a rule more like the old rule (where you can only "undo" something until you take another action) unless we see feedback that multiple undo is great.
Forgetting About Half-Written Inlines: It is now easier to lose track of inlines because we allow multiple simultaneous edits. For example: start writing an inline, scroll somewhere to look at something, catch another issue, add a new inline there, forget about your old inline.
Previously, you would be prevented from starting the second edit, which would remind you that you were doing something else. Now, the second edit will work independently, so you might more often forget about the first edit.
My hope is that the added flexibility is worth the increased opportunity for errors.
Part of the goal of the new scrollbar annotations is also to help with this, by providing a visual cue that makes it more difficult to forget that you have unfinished inlines.
Documentation: Some of this stuff could use documentation and blog coverage, but I expect to write that after completing T8909 + T8250 in 2-3 weeks.
Design Stuff: I don't think any of this looks too awful today, but design is evolving / nonfinal. See T12688 for some stuff we may look at.
Highlighting Rules: The rules around when lines are highlighted have changed a little. For example, lines are no longer persistently highlighted when editing a comment.
One reason for this is that it's now possible to edit multiple comments simultaneously, but there's currently only one highlighting reticle.
I believe the current behaviors are basically fine, although I liked some of the old behaviors slightly more. If multi-edit sticks, I may try to make the new behaviors a little more similar to the old behaviors. If we get rid of multi-edit, I'd likely make things very similar to the old behaviors.
Mouse "Prev" () and "Next" () Actions Removed: Previously, each inline had mouse navigation actions to jump to the previous or next inline. These have been removed. Rationale is: I believe they may be very rarely used, and removing them gives us more space to pursue changes like T11401 in the future.
You can perform a similar navigation action by clicking the inline comment's header to select it, then pressing n or p. You can also select it by clicking the scrollbar annotation (if prototypes are enabled), or just use the scrollbar annotations to navigate.
(You can also use n, p, N, P, j, k, J and K to navigate changes more broadly with the keyboard, and can take more actions without using the mouse.)
Feedback
We're open to feedback in these areas particularly:
- How do you like the persistent header element?
- How do you like the scrollbar annotation element?
- Is the greater editing/undo flexibility a net benefit (more power) or net loss (too easy to lose track of things / end up with a lot of clutter)?
- Do keyboard commands work better now? How does clicking inlines to select them feel?
- Anything that looks/feels like a bug.
