RFC for Open in Atom #1525
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,137 @@ | ||
| # Open in Atom | ||
|
|
||
| ## Status | ||
|
|
||
| Proposed | ||
|
|
||
| ## Summary | ||
|
|
||
| A quick way to switch from github.com to Atom. | ||
|
|
||
| ## Motivation | ||
|
|
||
| There are many ways how a user can discover new pull requests. There are also many ways where a user might save a pull request for later. But something that they all have in common: A URL. | ||
|
|
||
|  | ||
|
|
||
| At the time you decide to start working on something, chances are high you are on github.com or can click a link to github.com. Therefore let's make it easy switch from github.com and continue in Atom. | ||
|
|
||
| ### User Story: | ||
|
|
||
| In the morning Jody arrives at the office and checks their email. There are lots of notifications from GitHub. Jody briefly scans through them and stars the ones that look interesting or important. Then Jody keeps working on a new feature they started yesterday. After lunch, Jody decides to go back to their starred emails. A notification that got their interest is about a review request from a co-worker. Jody is eager to take a look and clicks on the link in the email. The browser opens and the PR page is shown. Jody reads through the conversation to understand what the PR is about, then switches to the "Files changed" to look at the code changes. Jody is thinking: "Hmm.. I wonder how it would feel to change the order?". | ||
|
|
||
| This is a moment where an "Open in Atom" feature would come in handy. Effortlessly switch from looking at a line on github.com to have the same line open in Atom, ready to be edited and tested locally. | ||
|
|
||
| Instead, Jody does the following: | ||
|
|
||
| 1. Scrolls to the top of the page | ||
| 2. Clicks on "Conversation" | ||
| 3. Scrolls to the bottom of the page | ||
| 4. Clicks on "command line instructions" | ||
| 5. Copies the `git checkout` part | ||
| 6. Opens Terminal | ||
| 7. CDs to the repo's directory | ||
| 8. Pastes the `git checkout` command | ||
| 9. Types `atom .` | ||
| 10. While Atom is opening, goes back to the diff to copy the line. | ||
| 11. In Atom, does a "Find in project" with the copied line | ||
| 12. Clicks on the found result | ||
| 13. Finally is ready to edit the line | ||
|
|
||
| How can we improve this "start on github.com, continue in Atom" workflow? How can the dozen of steps in the above example be reduced to just 1-2 clicks? | ||
|
|
||
| ## Explanation | ||
|
|
||
| In various places on github.com a user has the option to "Open in Atom". It's the same idea as the "Open in Desktop" that already exists. | ||
|
|
||
| > Note: Out of simplicity, GitHub Desktop or other editors are not shown in the mockups. If multiple options are available, a dropdown could be used to make a choice. | ||
|
|
||
|  | ||
|
|
||
| Once a user authenticates the GitHub package in Atom with their GitHub login, an "Open in Atom" option will be available on github.com in the following places: | ||
|
There was a problem hiding this comment. What happens if the user is on a different machine than the one that they have Atom installed on? Is it a no-op? I'm guessing that Desktop, Xcode, and all the others have to handle the same problem too, though, so it should be fine. 👍 There was a problem hiding this comment. Heh.. good question. 🤔 |
||
|
|
||
| ### Repo | ||
|
|
||
| 1. Clones the repo to Atom's "Project Home" (config) directory | ||
| 2. Opens a new Atom window with the repo as its project | ||
|
There was a problem hiding this comment. Would we want to offer a config option for new window / add to most recent window? Personally, I use There was a problem hiding this comment. Would be nice. I think if you clone in Atom, it adds a new project to the current window. Personally, I use the same Atom window, but try to switch between projects with packages like https://atom.io/packages/project-switcher2. So it replaces the current project in the current window. 😄 |
||
|
|
||
|  | ||
|
|
||
| ### Pull Request | ||
|
|
||
| 1. Clones the repo (if needed) | ||
| 2. Checks out the branch of the PR | ||
|
There was a problem hiding this comment. Note that this'll take a special refspec to fetch PR refs (in the common case of checking out a PR from a fork). We'll already need to cross that bridge to implement "checkout PR" anyway, though. |
||
| 3. Opens a new Atom window | ||
| - Or focuses the window if the repo already exists as an opened project | ||
| 4. Opens the GitHub panel showing the PR details | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ### Merge conflict | ||
|
|
||
| 1. Clones the repo (if needed) | ||
| 2. Checks out the branch | ||
| 3. Opens a new Atom window | ||
| - Or focuses the window if the repo already exists as an opened project | ||
| 4. Opens the Git panel (showing all conflicting files) | ||
| 5. Opens the (first) conflicting file | ||
| 6. Scrolls to the (first) conflict | ||
|
There was a problem hiding this comment. Related: we should also be doing this when you open a file from the Git tab, but we aren't yet; see #812. |
||
|
|
||
|  | ||
|
|
||
| ### File | ||
|
|
||
| 1. Clones the repo (if needed) | ||
| 2. Checks out the branch | ||
|
There was a problem hiding this comment. After each of these "checks out the branch" steps, we'll also need to do a fetch if the commit can't be found locally. Also, we'll need to make sure we choose the branch with a fetch upstream remote and ref matching the one on .com - they don't have to be named the same thing. There are some trailing edge cases to consider like "you already have multiple branches in your local repo that all fetch from the same place". |
||
| 3. Opens a new Atom window | ||
| - Or focuses the window if the repo already exists as an opened project | ||
| 4. Opens the file | ||
|
|
||
|  | ||
|
|
||
| ### Line | ||
|
|
||
| 1. Clones the repo (if needed) | ||
|
There was a problem hiding this comment. Similarly, for the "clone the repo (if needed)" steps - do you have any insight into how we can determine if the repo already exists or not? I'd rather not be too prescriptive about the way users organize their filesystems if we can avoid it. Maybe we can store a mapping of repository URL or nwo 👉 project path in a file under There was a problem hiding this comment.
Is
Yeah, it would become pretty annoying if you would have to tell Atom where to find the repo each time. I guess Desktop gets around that by having an index of all projects/repos so it knows their local path. There was a problem hiding this comment.
Nah, it's There was a problem hiding this comment.
🤔 I wonder if it's stored somewhere we could read and write? There was a problem hiding this comment.
Probably not from another application? Ohh.. now I just remembered.. Atom has this "Reopen Project":
Maybe we could check that list? Could be like:
Not sure where "Reopen Project" gets stored, but might be neat to have it as Scope creep! 😝 |
||
| 2. Checks out the branch | ||
| 3. Opens a new Atom window | ||
| - Or focuses the window if the repo already exists as an opened project | ||
| 4. Opens the file | ||
| 5. Scrolls to the line | ||
| 6. Shows a blinking cursor at the beginning of the line | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## Drawbacks | ||
|
|
||
| None that come to mind. | ||
|
|
||
| ## Rationale and alternatives | ||
|
|
||
| By reducing the friction for moving from github.com to Atom, we can improve the following: | ||
|
|
||
| - Higher quality of code reviews. | ||
| - Sometimes a reviewer might have the urge to suggest something, but they are not sure without testing it first. But since testing locally takes so many steps, they might just leave a comment like "Looks good to me" and move on. 👉 The easier it is to test changes, the better the reviews will become. | ||
| - More contributions. | ||
| - If a reviewer tests something locally and makes edits, they might commit the changes and push it back to the PR. 👉 Reviewers that can easily edit and test a PR more likely become collaborators. | ||
| - Better integration with other applications. | ||
| - Be able to open files, lines, merge conflicts etc. in Atom isn't just limited to github.com, it's also possible for other applications. For example if there is a merge conflict in GitHub Desktop, instead of manually switching and trying to find the conflict, GitHub Desktop could send you to Atom in a more seamless way. | ||
|
|
||
|
|
||
| ### Alternatives | ||
|
|
||
| An alternative is to let users discover PRs/issues or get notified about changes **within** Atom. This would certainly be nice to have, but it will be a very long road until a "never have to leave Atom" is reached. Especially for our tiny team. We also don't have to pick one or the other and both approaches can complement each other. | ||
|
|
||
| An alternative to have an Atom integration directly build into github.com would be to create a **browser extension**. A benefit is that it can be extended to other web sites/apps. For example an "Open in Atom" link inside Gmail for GitHub notifications. Downside: Users have to first install the extension. | ||
|
There was a problem hiding this comment. Yah, I much prefer this to writing browser extensions, I think - much more discoverable. There was a problem hiding this comment. This functionality could be easily implemented as a bookmarklet.
For example the following pseudo-link would send any URL to the This might be useful for prototyping or for users who want this functionality close at hand. Just a crazy idea. 😉 |
||
|
|
||
| ## Unresolved questions | ||
|
|
||
| - [ ] Is github.com interested in adding an "Open in Atom" option? And possibly other editors? There is already a [Clone in Xcode](https://blog.github.com/2017-06-05-clone-in-xcode/) option. | ||
| - [ ] Are there any security risks that need to be investigated beforehand. | ||
| - [ ] What could the API (URI) look like? E.g. `atom://github/open?pull=1234` | ||
|
There was a problem hiding this comment. Hmm, let's see. How about: And from an Enterprise instance, we'd encode the full remote URL: Hard to say until we start implementing it though, I'm sure there's more info I won't realize we need until we're neck-deep in code 😆 There was a problem hiding this comment.
Or in all cases? Would this be possible: Keep it exactly the same as .com URLs, except replace
This would make it easier to turn a .com URL into an Atom URI. By hand or by other apps, browser extensions etc. Also, as a first step, Atom could offer an "Open from GitHub URL" like in Visual Studio. Then later consider adding "Open in Atom" buttons to .com for an even better UX. There was a problem hiding this comment. Or even simpler: You'd need to escape the |
||
|
|
||
| ## Implementation phases | ||
|
|
||
| - [ ] Add an "Open in Atom" feature to the GitHub package. These URIs can already be "hand-composed" and for example pasted into Slack. Or used by other applications. | ||
| - [ ] Create a Chrome browser extension to first test adoption and get feedback. | ||
| - [ ] If it turns out to get a lot of usage, consider integrating directly into github.com. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does .com already handle this case where you have multiple "open in..." applications active? I'd imagine they have to, and it'd be nice to be able to take advantage of preexisting work.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Based on https://github.com/github/atom-log/issues/425#issuecomment-261125392, we should be able to add more clients. But that might only be for cloning a repo and not for all the other places.