85

Documentation assumes the same edit model as Q&A, where only one edit can occur at a time, and other editors must wait until an edit is complete to perform another one.

However, the actual model in Documentation is parallel edits from the same base. If multiple edits are queued and one is approved, all other edits now appear to roll back the approved edit, even though they had no intention of doing that (they couldn't have unless they were time travelers and knew the edit would be created and accepted and that they would want to roll it back).

This is compounded by the fact that an entire page is considered a single document when editing, so edits to separate examples and sections still conflict with each other. That's for a separate meta post though.

The current system where each approved edit clobbers all other parallel edits is chaotic. I end up rejecting perfectly acceptable edits because they unintentionally revert the other perfectly acceptable edit that was approved first.


After reviewing some edits I rejected, they appear differently. The individual edit diff seems to be against the revision the edit was made to, while the review diff was against the current revision. This seems to indicate that approving parallel edits will clobber already approved ones.

This edit doesn't indicate that any clobbering would happen, but during review it definitely showed that the Hello World example would be rolled back.

This edit shows that the Hello World example would have been reverted. The changes it shows to the example had not happened yet when they edited, and the author would have had no reason to revert them anyway.


Since edits can happen in parallel, there needs to be a way to merge edits that started from the same base.

14
  • 1
    One way to mitigate this problem is to use the Wikipedia model of editing sections. The problem is, though, that Wikipedia was made for highly structured text documents, and documentation is gonna have a lot of code. Commented Jul 21, 2016 at 18:02
  • 5
    As long as edits can happen in parallel this will still be a problem at the section level, especially with examples.
    – davidism
    Commented Jul 21, 2016 at 18:03
  • I'm not sure if Wikipedia's "resolve conflicts" step in the workflow would work, because it still seems to require a linear history. If we did that with Documentation edits, it would essentially be implicitly reviewing the earlier submissions.
    – davidism
    Commented Jul 21, 2016 at 18:05
  • 2
    MediaWiki actually attempts to merge edits when multiple happen at the same time. Only if it couldn’t be safely merged it will cause an edit conflict (which shows a diff and gives you the ability to resolve it).
    – poke
    Commented Jul 21, 2016 at 18:09
  • 3
    Can you add some examples, the edit pipeline does attempt to merge still-pending changes so this shouldn't happen. Wouldn't surprise me if there are bugs though. Commented Jul 21, 2016 at 18:17
  • 3
    @KevinMontrose It happened literally ever time I reviewed (and rejected) an edit in the flask tag docs.
    – davidism
    Commented Jul 21, 2016 at 18:18
  • @davidism I see this and this; but I don't quite see the overwrite? First one is explicitly changing the example, second one is tweaking one and adding one? Commented Jul 21, 2016 at 18:26
  • @KevinMontrose: Not sure if it's quite an example you're after, but maybe this post: meta.stackoverflow.com/questions/328605/… A minute or 2 before I approved an edit to the same topic. Commented Jul 21, 2016 at 18:36
  • @KevinMontrose when those were under review, the "no changes in this section" did not say that, they appeared to be reverting the previous edit.
    – davidism
    Commented Jul 21, 2016 at 18:38
  • 1
    @KevinMontrose oh, I see what's going on, the diff for the revision is against the revision it was made against, even if other revisions were approved in the meantime. Meanwhile, the diff in the review is against the current state of the page.
    – davidism
    Commented Jul 21, 2016 at 18:39
  • @KevinMontrose that second example is great because it's definitely clobbering a previous edit to the Hello World example. It's a straight revert of an edit that the editor couldn't have known had existed and wouldn't have any reason to revert.
    – davidism
    Commented Jul 21, 2016 at 18:47
  • 2
    Seeing the list of edits for other responses under the heading is really annoying. It is difficult to impossible to find if you are duplicating an edit when spammed with all of the other changes. Commented Jul 21, 2016 at 19:06
  • 1
    @KevinMontrose "... the edit pipeline does attempt to merge still-pending changes so this shouldn't happen." I wonder how the cases shall be solved where the attempt fails because the concurring edits aren't mutually exclusive. Commented Jul 21, 2016 at 19:29
  • 1
    Saw this today, as a result of this functionality, you can now see edit proposals like this Commented Jul 29, 2016 at 22:05

1 Answer 1

10

One solution to this issue is to make edits per section instead of per topic as Documentation should be editable by section suggests. However, that still leaves concurrent edits in the same example / section. These could probably solved in a similar way as Git does it. Making only edits on the same line conflict will probably be a good heuristic to prevent real write conflicts.

3
  • It sounds like the already have heuristics too, but that's not preventing parallel edits right now. Are you suggesting that if there are any conflicts an edit should be rejected automatically?
    – davidism
    Commented Jul 21, 2016 at 20:00
  • 2
    I'm really not clear what you're suggesting here. Could you provide an example? My question is about the fact that parallel edits overwrite each other when they don't conflict.
    – davidism
    Commented Jul 22, 2016 at 14:25
  • 2
    Another alternative is locking sections until an edit on it is reviewed. This may however slow people down, but editing conflicts (who votes on the conflict solution then) is also not trivial. Commented Jul 28, 2016 at 11:58

Not the answer you're looking for? Browse other questions tagged .