Undo discard documentation

[ccjmne]

Fixes atom/github#1716.

Added mention of the undo discard functionality, as redesigned with atom/github#1702. I tried being simple and concise, and to match the writing style of the rest of the manual.

I don't think an additional screenshot is necessary, seeing as the newer one for the Discard functionality itself does display the "Undo Last Discard" action in an available state, quite visibly.

Well, that; and, I'm worried I'd start breaking things that I don't wanna spend time fixing if I try and install unpublished/unstable packages! 🙄

[ccjmne]

Hey guys 👋,

This is my first contribution to the Flight Manual, and even one of my very firsts, globally. I did read through the contributing guidelines, but I may still have done things wrong: please don't hesitate to let me know!

I want to contribute, I don't wanna add more noise 🙂

[thomasjo]

// @atom/feedback

[Ben3eeE]

Thanks for contributing :bowing_man: and thanks for taking the time to look up the latest changes before submitting a PR :100:

I don't think an additional screenshot is necessary, seeing as the newer one for the Discard functionality itself does display the "Undo Last Discard" action in an available state, quite visibly.

I agree, the screenshot in https://github.com/atom/flight-manual.atom.io/pull/488 which this PR merges into shows the option already.

/cc: @kuychaco @simurai since this is currently merging into your branch to explain undo discard with the latest changes in beta

---

My :thought_balloon:s on this

It seems like the other options in https://github.com/atom/flight-manual.atom.io/pull/488 are explicitly spelled out. A suggestion could be to do the same and instruct the user to click "Undo Last Discard". Example:

To undo [...] click the <kbd>...</kbd> menu in the "Unstaged Changes" header and choose "Undo Last Discard"

I think conflicts when undoing should be explained in a little bit more detail than it is now, right now this is written like there are always conflicts and that the user always picked the option to merge with conflicts.

• Undoing the last discard doesn't always result in merge conflicts
• When there are conflicts there is a dialog that shows up. Maybe a screenshot of the dialog and/or a short explanation what each option does

It doesn't have to be much, an example:

If there are conflicts when undoing you will get an option to cancel the undo or to merge with conflicts ... works similarly to cherry-picking ...

[ccjmne]

@Ben3eeE Thanks for the review! 🙇

I agree with your points, I've been a little light on the details 😶.

Actually, in my version – Atom version 1.32.0 (latest) w/ atom/[email protected] (latest published version), I do get conflicts everytime I undo a discard. Even when there should be none (if I were to simply git stash, git pop instead).

Steps to reproduce:

• git reset --hard
• echo "Discard me" >> content/using-atom/sections/github-package.md
• Access the Git panel in Atom
• Locate modified file, right-click, "Discard Changes" (or Ctrl-Backspace)
• Click "Undo Discard"

... Does consistently alert me that "Undoing will result in conflicts". ❌

To be specific: it only "conflicts" when the discarded changes were to an existing, tracked file. Had I gone for echo "Discard me" > newfile.deleteme and "Discard ... Undo" in Atom's Git panel, it would have worked seamlessly 👍.

The same scenario using git stash:

• git reset --hard
• echo "Discard me" >> content/using-atom/sections/github-package.md
• git stash -- content/using-atom/sections/github-package.md
• git stash pop

... Works just fine, with no conflict. ✔️

I should try and install the (unpublished) branch that reworks the "Undo Discard" functionality, though – I was a bit afraid I'd have troubles doing this, then getting back to using only the released and published versions, but considering I'm documenting it... my not checking it out is at least an oversight 😶.

There seems to be no issue raised about "undo discard conflicts" in github/atom. If I can still reproduce it after having set up the latest version, do you reckon I should report this unexpected behaviour?

---

I'm gonna attempt to:

• Disable core/github from Atom
• git clone atom/github (clone it)
• Checkout master (where atom/github#1702 is merged)
• npm install ... build ... (build it)
• apm link (install it)
• Restart Atom

Would that be the correct procedure for updating to the very latest (0.22.1) version of atom/github?

[ccjmne]

Nevermind me, there's a procedure for using the nightly version of the package. Sorry about that!

[Ben3eeE]

There is a guide in this flight-manual on how to contribute to official packages: https://flight-manual.atom.io/hacking-atom/sections/contributing-to-official-atom-packages/ It will guide you through the steps.

I believe these changes are on the latest beta that was released yesterday. So another option is to install the latest beta and check it out there :slightly_smiling_face:

Edit: Oh or the github package guide :+1:

[ccjmne]

Thanks @Ben3eeE !

I decided to use Atom beta 🙂. I can confirm Atom beta ships (today) with atom/[email protected], which does have the changes to "Undo Discard" merged in.

I disabled all my community packages that have anything to do with git, just to be sure, but I still get an "Undoing will result in conflicts" popup for any file that is tracked! Does it happen only to me? I'm running the whole thing on Windows 10 right now. Maybe there's my mistake 🙄.

Would you have time to try and reproduce it? I feel like it would have been noticed and discussed before, if it wasn't just happening to me – but right there I'm quite perplex.

[Ben3eeE]

I am seeing the same behavior as you. Maybe it is the expected behavior. I am not sure since I very rarely use the button 🙂

When I wrote my comment I tested with a new file I just created to see if there was a scenario where there wasn't any conflicts and that's the only scenario where there isn't any 🙂

[ccjmne]

Yeah, maybe it's not unexpected 😶.

After all, I originally thought it was intended that way (even though I wasn't expecting it); but I can't know for sure: The Flight Guide isn't very specific about that topic 😉

I'm away right now, but I will:

• implement the changes you suggested
• create an issue in atom/github just to mention that I think it odd that:
  "Undo Discard", without any changes to the file since the corresponding "Discard Changes", results in conflicts.

Thanks for bearing with me 🙇

[ccjmne]

Looks like the Travis build failed there (stating line 804):

• ./output/behind-atom/sections/configuration-api/index.html
  • External link https://atom.io/docs/api/latest/CompositeDisposable failed: 404 No error
• ./output/upgrading-to-1-0-apis/sections/upgrading-your-package/index.html
  • External link https://atom.io/docs/api/latest/Disposable failed: 404 No error
  • External link https://atom.io/docs/api/latest/Emitter failed: 404 No error rake aborted! HTML-Proofer found 3 failures!

The external web pages are indeed unavailable.

My own build (script/bootstrap && script/server) works fine.

[Ben3eeE]

Don't worry about the build failure. There is an issue with these pages in Atom 1.32 https://github.com/atom/atom/issues/18308.

I'll review this as soon as I can 🙂