Repository navigation
Discussing Create PR #620
Description
We just looked again Ashi Krishnan (@queerviolet)'s PR. It's a viable path since it's close to the web UI experience. But it made us think again about how to keep the PR creation experience as close as possible to the VS Code UX. Below is an attempt to capture our discussions starting with restating some goals.
Goal
- Ensure users don't have to leave the editor to create a PR. (There are steps users have to take today in order to create a PR such as creating a branch, pushing commits to the branch, ensuring that the branch is in a good shape. All of this can be done in the editor today. So, we can start with assuming the same.)
- Integrate tightly with the markdown editing experience. This is actually not limited to "Create PR" since this is also a challenge for comments in general.
- Fit in the overall VS Code experience; i.e. maintain the perceived lightweight nature of VS Code.
Proposed Flow for first iteration
-
User is reponsible creating branch, push branch, nesure branch is in good shape. Just as they are if they use the web UI.
-
User chooses
Create Pull Requestfrom command palette. Same as PR. -
This opens the QuickPick with 3 steps and a
Createbutton, and the user fills in the data- Title of the PR
- Target repository (dropdown list)
- Target branch (dropdown list)
→ This creates the PR on GH.
→ VS Code switches to the same mode as if the user would have checked out a PR, and it opens the Overview page of the PR.
- User hits the edit button next to the description of the PR
→ Description switches into edit mode.
→ Text field has an affordance to "maximize/flyout".
- User hits the
Maximizebutton.
→ Markdown editor opens on synthesized document (extension is the document provider). Extension listens to all document changes and live updates the draft of the description (same for comments).
-
User uses the markdown text editor to write the description, they can use the markdown preview to see what the markdown would be rendered.
-
User closes the markdown editor (or switches back to the Overview page)
→ Description is the same as it was/is on the markdown editor.
- User submits/saves draft.
What we need
- Ensure draft comments are maintained when switching away from the Overview Page. Peng Lyu (@rebornix) is working on this.
- Ensure we can edit. Rachel Macfarlane (@RMacfarlane) is working on this.
- QuickPick: The steps show the same information as the current PRs (see below) just in a linear fashion. The same data is needed to create the QuickPick items.
- Have the "maximize". Not yet taken. Close to what Ashi Krishnan (@queerviolet) experimented with.
Activity
queerviolet commentedon Oct 25, 2018
A previous version of #554 used input boxes; going back to that and making them a quick pick would be straightforward.
Kai Maetzel (@kieferrm), I liked your idea of leveraging Markdown editing inside VS Code.
What if the create PR button opened two panels? The first one would just be
$repo/.git/PULL_REQUEST.md:The second would be a pull request preview pane. This should be similar to, but different from, the standard Markdown preview pane. It should look more like a PR, and should render markdown closer to how it appears on GitHub.com. For example, when we add support for cross-referencing PRs, issues, and @-ing users, all those links should appear in the preview as well.
We can auto-populate
PULL_REQUEST.mdif it doesn't exist using the heuristics we currently do, and we can use Intellisense to suggest valid branches, repos, and forks.I don't love starting the flow with a bunch of modals, mostly because I think it's unnecessary. In the typical case, we can look at the remotes and infer what you want to pull from where. It's two extra keystrokes to accept these defaults, but I think we just don't need those at all. If we guess wrong, the user can still easily edit the markdown frontmatter. Intellisense completions in that space feel better to my coderly mind and fingers.
Also, having the draft pull request be a file lends a nice solidity to it—we don't have to do anything special to avoid losing a user's work. It's also nicely parallel with how git itself manages commit messages.
The worst part of this whole experience is having to open up two panels, one for
PULL_REQUEST.mdand one for the preview, but I suppose this is close enough to the Markdown preview workflow that it's acceptable? I can't really see a way around it, either. I'm down with having an affordance to activate and deactivate the editor panel (and similar affordances on comments), but I think in this case it should start activated. Why make the user click another button to start editing the PR, which they are definitely going to want to do?queerviolet commentedon Oct 25, 2018
Something like this (from exp/create-pr-preview):
drguthals commentedon Oct 25, 2018
👋 We have some thoughts about including the entire
Create PRexperience in one MD file. I really love the demo that Ashi Krishnan (@queerviolet) created in the comment above this.There are some things coming down the GitHub pipeline that I would love to include in PR creation that would be made more difficult if we first created the PR with only a title and the branch/remote set then added the rest. I would prefer adding it all at once, with the description still being optional and editable later.
💭 ?
kieferrm commentedon Oct 26, 2018
Here is a demo Peng Lyu (@rebornix) put together of the flow I described above. It still misses the edit buttons (WIP) and the max/fly out. After the user pressed the flyout, the experience would be quite similar to what @queerviolet shows above. The quick pick right now only shows locally defined remotes and local branches but with the code that the PR already contains it seems we could easily extend this. If the PR does not need a description, we could also provide a short-cut exit, i.e. something that creates the PR but instead of staying on the branch returns to master right away while still informing the user about whether or not the PR creation was successful.
kieferrm commentedon Oct 26, 2018
Comparing both approaches, I can see pros and cons for both. The one thing that appeals the most to me with the approach I described is uniformity. I.e. when it comes to editing descriptions or long comments I can always use the maximize/fly-out to matter whether I create a PR or review a PR, or respond to a reviewer's comments. I can see us testing both approaches with users.
rebornix commentedon Oct 26, 2018
Similarly to Ashi Krishnan (@queerviolet) 's demo in #620 (comment), here is what the commenting editor max/flyout looks like
Once we have the edit button for description/comment, we can edit them in a normal markdown editor and the content change in the markdown editor is saved to the description page when save (auto save is even better).
drguthals commentedon Oct 27, 2018
It would be great to test out both with users, I love that idea! We can setup some UXR for early November with these two approaches.
Thanks for the two gifs 🎉
Ghostbird commentedon Jan 22, 2019
I don't like one thing about #661: It defaults the PR title to the last commit message. However, whenever I make a PR, my last commit is generally not the main commit of the branch, but a clean-up or maintenance commit. Which means that my PRs are almost always created with nonsensical titles.
kieferrm commentedon Feb 1, 2019
Gijsbert ter Horst (@Ghostbird) can you pls create a new issue. Thanks!