New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

GitHub package long-term vision notes #1372

Merged
merged 12 commits into from Apr 21, 2018

Conversation

Projects
None yet
4 participants
@smashwilson
Member

smashwilson commented Apr 2, 2018

Wordsmithing of the notes from a series of meetings with @kuychaco and @daviwil the last time we were at HQ. This is a collection of thoughts about our overall philosophy with this package and our current understanding of its scope and goals. It's also going to include a running list of farther-reaching ideas we'd love to explore.

馃帹 Rendered in all its markdown-y glory.

/cc @atom/github-package to make sure I'm accurately reflecting our views 馃槃
/cc @Haacked @sguthals

smashwilson added some commits Apr 2, 2018

@smashwilson smashwilson added this to In Progress 馃捇 in Short-Term Roadmap Apr 2, 2018

@smashwilson smashwilson self-assigned this Apr 3, 2018

smashwilson added some commits Apr 20, 2018

@smashwilson smashwilson changed the title from [wip] GitHub package long-term vision notes to GitHub package long-term vision notes Apr 20, 2018

smashwilson added some commits Apr 20, 2018

@smashwilson

This comment has been minimized.

Member

smashwilson commented Apr 20, 2018

Okay, I think I've transcribed all of my notes from our working sessions while I was in San Francisco. I'll likely merge this tomorrow-ish so we can find it in master. I'd 鉂わ笍 any comments or edits or additions that anyone has to offer, though, and of course we can always make more pull requests.

@sguthals

This comment has been minimized.

Contributor

sguthals commented Apr 20, 2018

Thank you @smashwilson!

Ill take a look tomorrow - this will be great for the mini-summit next week!

@smashwilson

This comment has been minimized.

Member

smashwilson commented Apr 21, 2018

Merging because if I don't then I'll never consider it "done." We can always refine later 馃暀

@smashwilson smashwilson merged commit 7e01d64 into master Apr 21, 2018

3 checks passed

ci/circleci Your tests passed on CircleCI!
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

Short-Term Roadmap automation moved this from In Progress 馃捇 to Complete 鉁 Apr 21, 2018

@smashwilson smashwilson deleted the vision branch Apr 21, 2018

@smashwilson smashwilson removed this from Complete 鉁 in Short-Term Roadmap Apr 23, 2018

@simurai

This comment has been minimized.

Member

simurai commented Apr 23, 2018

This is all very well written and without going too much into details. Perfect as a vision. 馃憤

As much as possible, we adhere to git terminology and concepts, rather than inventing our own. This allows users who learn git with our package to transfer their knowledge to other git tooling, and users who know git from other contexts to navigate our package more easily.

In the past, I wondered: "Why can't we make it easier, especially for beginners, by abstracting/hiding some of Git". But "this allows users to learn git" is a good point.

@Haacked

This comment has been minimized.

Haacked commented Apr 23, 2018

In the past, I wondered: "Why can't we make it easier, especially for beginners, by abstracting/hiding some of Git". But "this allows users to learn git" is a good point.

I'm not necessarily convinced. It's like suggesting we should have all our programming languages be more complicated so they map to terms and concepts to make it easier for users to learn assembler.

I think what holds us back from building an abstraction on top of Git is that if we do so, we have to commit to it end-to-end across GitHub and in a deep manner. Otherwise we end up in an XKCD standards scenario. 馃槣

Think of it this way, our mission isn't to teach people to use Git. It's to help them write software together. Git is currently just a means to an end. I don't care about Git. I care about our users ability to write code collaboratively.

If we look at git.exe as being like assembler, then we want to build a higher level version control that uses git under the hood. It's the difference between assembler and a memory managed language like Ruby. Suddenly, we've unlocked a ton of productivity.

@simurai

This comment has been minimized.

Member

simurai commented Apr 24, 2018

I think what holds us back from building an abstraction on top of Git is that if we do so, we have to commit to it end-to-end across GitHub and in a deep manner.

Yeah, that's great point. It feels like an "all or nothing" deal.

Think of it this way, our mission isn't to teach people to use Git. It's to help them write software together.

Ok, maybe I should rephrase it to: If people learn how to use the GitHub package (with Git terminology), it makes it easier for them to move to the command line or other Git clients that also use Git terminology. I guess you could argue that that shouldn't be our goal either. But I still think there is some value in easing that bridge. At least currently.

At the same time I like how Desktop tries to be more beginner friendly by having only a single list with checkboxes and no mention of staging/unstaging. It becomes more a "just keep things selected that should be part of the next commit".

@smashwilson

This comment has been minimized.

Member

smashwilson commented Apr 25, 2018

I look at git less as assembler and more as JavaScript. It has its sharp edges and its embedded sins, but it's also become the lingua franca of modern software collaboration, because it's what's there. Maintainers and collaborators use git terminology to interact; see, for example, the "please rebase" comment.

It's also intimidating for the uninitiated and even weaponized as tech gatekeeping. There are other projects that aim to make git more approachable by changing its terminology, but I would be afraid of creating a walled garden. We may be able to make users more comfortable within our own grounds, but if we aren't careful, they'll still experience a harsh awakening when they first attempt to venture outside.

What I want to do is have our cake and eat it too: I want to create novel graphical porcelain that makes git approachable for the casual user; but I want to do so in a way that uses the language that people already use when they're talking about git. If an Atom user tries to contribute to a project and is asked to "please rebase," they should be able to open the command palette, type "rebase", and figure out what they're being asked to do. Or, if an Atom user sees "rebase" in a context menu, they should be able to Google "rebase" and figure out what that means from existing git documentation.

A nice side benefit is that this helps us be more useful for the git expert as well. By using familiar terminology we improve the discoverability and comfort of our features that map to git CLI porcelain.

Of course, maybe I'm just underestimating our ability to make the world change 馃槃

I'll also note that Desktop had a similar thought process in their design around the sync button, which was omitted from the redesign:

A very common feedback with the current clients has been that the sync button is scary. We believe that it currently serves two groups of users very well, the first being those who deeply understand Git and realize what it's doing and the second is those users who have deep trust in the app and doesn't care all that much about its inner workings. It doesn't work so well for the remainder of users and various suggestions have been made over the years on how to address this. The most current thinking being that we'd keep it but with some sort of combo/dropdown so that users could explicitly pull or explicitly push.

[...]

We've opted for using Git terminology primarily so that the button text is something users can throw into Google in order to understand what the action does. Additionally in the case of errors we'll be able to present the underlying error as received from Git to the user (for them to Google). Note that this concept assumes that we keep background fetching in TNG:9000 as we'll need to reflect changes to the remote.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment