From 040baa86d66f14b7feb4ea2026f3363f736b9bd9 Mon Sep 17 00:00:00 2001 From: Ash Wilson Date: Fri, 1 Feb 2019 15:30:04 -0500 Subject: [PATCH 1/3] Text write-up --- .../005-identity-and-context.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/feature-requests/005-identity-and-context.md diff --git a/docs/feature-requests/005-identity-and-context.md b/docs/feature-requests/005-identity-and-context.md new file mode 100644 index 0000000000..a01fbbd165 --- /dev/null +++ b/docs/feature-requests/005-identity-and-context.md @@ -0,0 +1,99 @@ +**_Part 1 - Required information_** + +# Identity and Context Tiles + +## :memo: Summary + +Add a small tile to the top of the Git and GitHub dock items to display and manage contextual information like the currently authenticated user and the active git repository. + +## :checkered_flag: Motivation + +All of our Git and GitHub actions and displayed information track a "current repository" that follows the path of your active pane item. Historically, this has been a source of confusion for users: + +* If you have no changes and are on the default branch in two repositories, there is no visual indication of which repository is the "active" one. _(This has bitten me personally more than once when I create a new branch in the wrong repository by mistake, and I wrote the damn thing.)_ +* When adding a new project folder, the current repository remains the previous one until you open a file within the new folder. +* Opening a new file that isn't within a git repository causes the git panel to revert to its "initialize here?" state, which is jarring when you want to make quick external edits. + +We also have a host of long-standing issues related to identity management: + +* There is no way to configure your git username and email address on first install. This means that a new user who doesn't have git installed on their machine already still needs to do so, even though we bundle a git binary as part of Atom! _(Okay, technically, you can create a `~/.gitconfig` with the appropriate values by hand. That kind of sucks though.)_ [#932](https://github.com/atom/github/issues/932) +* Our Git item provides no indication of what identity it's going to use to create a new commit. This can cause friction for users who use different email addresses for work and personal projects or who wish to use masked `@noreply` email addresses. +* Our GitHub item provides no indication of the current GitHub user. While I don't expect that managing multiple GitHub accounts is a common need, it can arise in situations like shared machines. +* Our GitHub item gives you no way to log out or re-authenticate as a different user. _(You can do it by running `GitHub: Logout` from the command palette, but this is not discoverable.)_ [#1693](https://github.com/atom/github/issues/1693) + +And, finally, the mechanism to refresh the GitHub tab with new data is completely hidden. + +## 🤯 Explanation + +### Git context and identity tile + +The Git tab has a _context and identity tile_ at its top that displays: + +* The GitHub avatar corresponding to your current git identification, as read by `git config user.email`. If no GitHub account is associated with the configured email address, a placeholder is shown instead. On hover, your full git identification is shown in a tooltip (_Real Name _). Clicking your avatar opens the "introduction" view to allow you to change your configuration. +* The path to the currently active git repository, shortened in a way [consistent with the way project folders appear in tree-view](https://github.com/atom/tree-view/blob/master/lib/tree-view.coffee#L336). If multiple repositories are available, this is a drop-down menu allowing you to change the active repository. + +> "Available" repositories are discovered by taking the set of paths from: +> * Project root folders +> * Paths of open pane items +> * `getWorkingDirectoryPath()` results from open github package pane items +> Then locating the set of git repositories containing each (if any) using `git rev-parse --show-toplevel` and +> `git rev-parse --absolute-git-dir`. + +> TODO: Git context and identity tile graphic + +### GitHub context and identity tile + +The GitHub tab has a _context and identity tile_ at its top that displays: + +* The GitHub avatar corresponding to the currently logged-in GitHub user. On hover, the GitHub username is displayed in a tooltip (_@smashwilson_). Clicking your avatar reveals the `GithubLoginView`. +* The path to the currently active git repository, as in the Git context tile. +* A refresh button. On click, the information displayed in the GitHub tab is re-fetched. + +> TODO: GitHub context and identity tile graphic + +### Git introduction view + +If you haven't configured `user.email` and `user.name`, the Git tab displays the _introduction view_. This view allows you to see and enter your name and email address. + +> TODO: introduction view graphic + +### GitHub login view + +> TODO: GitHub login view + +**_Part 2 - Additional information_** + +## :anchor: Drawbacks + +This occupies prime vertical graphical real estate in our already-small dock item display area, which users will likely not need to interact with often. + +Not all users have GitHub accounts. Displaying a GitHub avatar on the Git tab item may be off-putting. + +## :thinking: Rationale and alternatives + +_TBD_ + +## :question: Unresolved questions + +* If only one git repository is available, should we bother rendering it in the drop-down menus, or omit it to save visual noise? +* Is the avatar-with-tooltip pattern a reasonable compromise to save space? +* Should we make an attempt to differentiate between multiple git repository paths that share the same basename? +* Can we detect when a user has configured GitHub's email anonymity and populate their `git user.email` accordingly? + +## :warning: Out of Scope + +* Configuring different identities for different git repositories. We should read the git user information with `git config`, but always write with `git config --global`. + +## :construction: Implementation phases + +_TBD_ + +## :white_check_mark: Feature description for Atom release blog post + +_TBD_ + + From 7b1996fbaa6cdf7b8b9540e7569e988c3510251a Mon Sep 17 00:00:00 2001 From: simurai Date: Mon, 11 Feb 2019 15:23:11 +0900 Subject: [PATCH 2/3] Add git + github screenshots --- docs/feature-requests/005-identity-and-context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/feature-requests/005-identity-and-context.md b/docs/feature-requests/005-identity-and-context.md index a01fbbd165..6a5dfa90ee 100644 --- a/docs/feature-requests/005-identity-and-context.md +++ b/docs/feature-requests/005-identity-and-context.md @@ -39,7 +39,7 @@ The Git tab has a _context and identity tile_ at its top that displays: > Then locating the set of git repositories containing each (if any) using `git rev-parse --show-toplevel` and > `git rev-parse --absolute-git-dir`. -> TODO: Git context and identity tile graphic +![git](https://user-images.githubusercontent.com/378023/52548367-abe86780-2e10-11e9-9dc1-8c4e3c2ad098.png) ### GitHub context and identity tile @@ -49,7 +49,7 @@ The GitHub tab has a _context and identity tile_ at its top that displays: * The path to the currently active git repository, as in the Git context tile. * A refresh button. On click, the information displayed in the GitHub tab is re-fetched. -> TODO: GitHub context and identity tile graphic +![github](https://user-images.githubusercontent.com/378023/52548380-b86cc000-2e10-11e9-9899-110306c2153c.png) ### Git introduction view From 79d6f3037c4a5ea3cb42a1edd76025e5ada5bd22 Mon Sep 17 00:00:00 2001 From: simurai Date: Mon, 11 Feb 2019 16:10:47 +0900 Subject: [PATCH 3/3] Add git identity and GitHub login screenshots --- docs/feature-requests/005-identity-and-context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/feature-requests/005-identity-and-context.md b/docs/feature-requests/005-identity-and-context.md index 6a5dfa90ee..135b72aae4 100644 --- a/docs/feature-requests/005-identity-and-context.md +++ b/docs/feature-requests/005-identity-and-context.md @@ -55,11 +55,11 @@ The GitHub tab has a _context and identity tile_ at its top that displays: If you haven't configured `user.email` and `user.name`, the Git tab displays the _introduction view_. This view allows you to see and enter your name and email address. -> TODO: introduction view graphic +![identity](https://user-images.githubusercontent.com/378023/52549612-59f71000-2e17-11e9-84ff-c6c36bf5c015.png) ### GitHub login view -> TODO: GitHub login view +![login](https://user-images.githubusercontent.com/378023/52549614-5a8fa680-2e17-11e9-984a-f7eaf20c0f48.png) **_Part 2 - Additional information_**