GitHub package long-term vision notes

docs/vision/README.md

@@ -0,0 +1,36 @@
+# Long-term vision
+
+This directory contains notes on ideas for the longer-term vision of the @atom/github-package core team for this package. We intend to use the documents in this space to:
+
+* Articulate the objectives we have for the package as a whole. The features we add should contribute to a cohesive experience, not be an amalgamation of unrelated things that sounded cool at the time.
+* Delineate our boundaries. We should be able to reference these documents to say why we _won't_ work on a feature in addition to why we will.
+* Incubate that long tail of ideas we're excited about that we aren't ready to write in [RFC](../how-we-work.md#new-features) form yet.
+* Inform our quarterly and weekly planning cycles. We intend to revisit these often as part of our team's planning cadence, both to keep them accurate and timely and to cherry-pick from when we can.
+* Share our vision with the world and let the world share its vision with us. :earth_americas:
+
+## So when are you building all this stuff then
+
+The inclusion of a feature here is **not** a commitment to our delivery of said feature on any particular timeline.
+
+Some we may never implement. Some may be unrecognizable from their descriptions here. Others we may deliver in a matter of months. We don't know yet! This is the place where we put ideas that we explicitly haven't fully plumbed the depths of and prioritized against our other work. It turns out that it's a lot easier to write a bunch of markdown than it is to get all of the code working.
+
+If you want to see our plans for what we _are_ working on in the very near term, at various layers of granularity:
+
+* Our [short-term roadmap project](https://github.com/atom/github/projects/8) is where we track the issues and pull requests we're working on a day-to-day basis.
+* The [`docs/focus` directory in `atom/atom`](https://github.com/atom/atom/tree/master/docs/focus) contains weekly progress and planning updates from the entire core Atom team, including us.
+* Our intermediate-scope plans are listed in [the `#github-package` section of the focus README.](https://github.com/atom/atom/tree/master/docs/focus#github-package)
+
+## This sounds cool, how can I help?
+
+I'm glad you asked!
+
+The first step in tackling any of these would be to [submit an RFC](../how-we-work.md#new-features). The ideas described here are very rough - before we can get to work shipping any of them, we need to reach consensus on scope, graphic design direction, user experience, and many other details. If one of our bullet points sparks your imagination, start a draft of the writeup following [the template we provide](https://github.com/atom/github/blob/master/docs/rfcs/000-template.md). It doesn't have to be complete, but it's a great way to get involved and start a more in-depth conversation.
+
+If that sounds like not much fun to you, and you'd rather just write some code: try making a proof-of-concept as a separate Atom package! Tell us about it in an issue and show us what you've done. If we like it and you're okay with it, we can help you merge it into this package, or we can help provide the proper plumbing to make it an independent thing.
+
+## Table of Contents
+
+* [`who.md`: Our target audience](./who.md)
+* [`git.md`: Git integration](./git.md)
+* [`github.md`: GitHub integration](./github.md)
+* [`ideas.md`: Proto RFC incubator](./ideas.md)

docs/vision/git.md

@@ -0,0 +1,29 @@
+# Git integration
+
+## Why does this exist
+
+The primary purposes of the git integration are:
+
+1. **Reduce context switching.** We can improve productivity by reducing the number of times you need to switch to a terminal (or Desktop or other external tool) to perform routine tasks.
+2. **Streamline common workflows.** We want users to be able to perform the motions of commonly used workflows with minimum friction (hunting through menus or the command palette).
+3. Improve **discoverability of git features.**
+4. Provide _confidence and safety_ by **always being able to back out of a situation.**
+5. Go _beyond what you can do on the command line_ with **graphical porcelain.**
+
+## Boundaries
+
+We want to focus on the basics - fundamental, primitive git operations that can be composed to form many workflows. To contrast, we do _not_ want to target completeness.
+
+We will extend beyond this for features that are _uniquely useful in the context of an editor_:
+
+* Modifying diffs before staging or committing
+* Shaping commit history to tell a story
+* Visually exploring someone else's commit history
+* Enhanced debugging and troubleshooting backed by tools like `git bisect` and `git blame`.
+* Improve merge conflict resolution by taking advantage of tree-sitter ASTs
+
+Or for those that provide richer visualizations of git's state, like a log view.
+
+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.
+
+We also exert ourselves to stay in sync with the real state of git on the filesystem, including the index, refs, stashes, and so forth. We want it to remain easy to go to and from the terminal at will.

docs/vision/github.md

@@ -0,0 +1,19 @@
+# GitHub integration
+
+## Why does this exist
+
+The primary purposes of the GitHub integration are:
+
+1. **Reduce context switching and friction** from _unnecessary_ trips to the browser and back. Shifting to the browser should occur at natural inflection points within a developer's workflow.
+2. **Bring asynchronous collaboration closer to your code.**
+3. **Notifications of events** such as new comments or build status. We want to surface information in a timely and convenient manner.
+4. **Graceful introduction to sharing and working on GitHub.** Include _gentle_ nudges toward best practices and commonly-used conventions, without being overly prescriptive.
+5. **Provide features that aren't possible anywhere else** because of the context and presence that the package has.
+
+## Boundaries
+
+This package should _not_ attempt to replicate the design of github.com within your editor. It turns out that github.com already exists! Also, a much larger number of people are working on it than are working on this package, so trying to stay up to date with it is... unrealistic.
+
+Instead, we want to prioritize features that are _enhanced by the state and context that are uniquely available within Atom_. The package can take advantage of its knowledge of the repository, branch, file, and so on that you're looking at :sparkles: right now :sparkles: to save you time.
+
+We will also consider functionality that allows you to _defer and stage actions to complete in more detail later with the full browser experience_. By allowing you to batch actions that should naturally occur on the website into longer sessions, we can help provide longer sessions focused on your code within the editor.

docs/vision/ideas.md

@@ -0,0 +1,48 @@
+# Crazy Idea Free-For-All Grab Bag
+
+_In no particular order_
+
+* Add informational popups and make subtle changes to UI verbiage to improve the experience of novice git users. We want to provide _subtle_ guidance and education that can nudge users to the common, recommended next steps, with some knowledge of what they're doing.
+
+* Improved remote and branch management. Our current `BranchMenuView` is limited and unscalable.
+  * Initiate branch merges and rebases in-editor.
+  * Delete branches.
+  * Specifically, delete local branches that have already been merged into the repository's main branch.
+  * Prune remote tracking branches.
+  * Manage remotes: add new ones, delete existing ones, rename or set URLs for existing ones.
+
+* Initialization, providing username and email.
+  * "You're committing with email address X" as a prompt for those who use different email addresses for different projects.
+
+* Rework the WorkerManager, either with [WebWorkers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) or the [spawn-server](https://github.com/nathansobo/spawn-server). Our current solution with a hidden render process is heavyweight.
+
+* Create a PaneItem for arbitrary, multi-file diffs. Closely related: implement a commit viewer, which is basically that with a header for the commit message and metadata.
+
+* Stashing.
+
+* Git Virtual FS. It isn't clear if we'd even need to do anything to support this, but we should at least test with it.
+
+* An interactive, navigable log view. Visualize your full commit history graph, including refs. Filter and search commits by author, message, or diff content. Merge by visually linking the merge bases. Rebase or cherry-pick by dragging and dropping commit nodes around. Revert or reset refs from a context menu.
+
+* Blame information, in-editor, on demand.
+  * Navigate from blame to the commit and pull request that introduced it. Include cross-references for quick navigation.
+
+* Editable diffs.
+
+* Enhanced reflog. Pane item that displays and searches everything that `git reflog` shows you, interleaved with additional events that git is unaware of but Atom is (like discards). For each displayed, action, provide an explanation, and a collection of possible actions to "undo" its effect, along with a description of the implications of each. For example, for a commit event, offer a revert or a rebase, and advise one or the other depending on whether or not the commit has been pushed to a remote or not.
+
+* "Where is my code?" Given a pull request, show the tags or GitHub releases that include it. Given a commit, find the pull request that introduced it.
+
+* Provide context behind merge conflicts. For a specific conflict, identify the exact commits reachable from each parent that introduced a conflicting hunk.
+
+* Automatic CHANGELOG generation.
+
+* Release creation.
+
+* Show diffs from "far away" - code that has been pushed to elsewhere in your repository's fork network, but that you haven't explicitly fetched yet.
+
+* Provide advance warning when local changes will have merge conflicts with changes on a remote.
+
+* "Here's what's changed." View pull requests and other recent activity on pull to see what's different.
+
+* Issue drafts. Write quick notes to yourself as the thoughts occur to you, then open them all at once as issue drafts on github.com when you're ready to flesh them out and share them.

docs/vision/who.md

@@ -0,0 +1,43 @@
+# Our audience
+
+_Who are the intended users of this package?_ An important prerequisite to determine what to build and when is to know who you're building for. When you're working on developer tools it's easy to fall into the trap of overfitting to your own workflow and processes. Keeping the full range of our user base in mind while designing can help ensure that the features we build are useful to as many people as possible.
+
+We can segment our user base along the following axes:
+
+## Git familiarity
+
+### Beginning git users
+
+This group includes both new developers (university CS students, precocious high schoolers, professionals in other fields who are interested in joining tech) and those in tech-adjacent professions (technical writers, support).
+
+As a tool, command-line git is very punishing to those who attempt to learn it "in passing" while they're really trying to accomplish something else. It takes a few days of focused study to really click, and until you spend it it's a source of great frustration.
+
+We can help by providing a _gentler introduction to git_ to increase the intuitiveness of those early days. Ideally, someone with no git experience should be able to make a contribution to a project without having to take a class or read a book first. Furthermore, we can _set learners up for future success_ by providing hints and nudges and using terminology that will click later.
+
+My dream is to make an answer to "so, how do I use git" be "oh, just use Atom to get started".
+
+### Experienced git users
+
+These are our users who already use git daily and know command-line incantations inside and out. We want to remain appealing enough to be useful to users who are already comfortable elsewhere, even if only sometimes.
+
+We can serve these users by _reducing context switches_ for the most common tasks. Reducing the number of times you need to change your active desktop window is a productivity win.
+
+The terminology and verbiage we use throughout the package can help _preserve the usefulness of existing knowledge_. Someone who's comfortable with git at the command line should be able to predict at a glance what any given UI action will take.
+
+Finally, we can also introduce _novel git affordances_ that aren't easy to accomplish at the command-line to go above and beyond and give people some extra flair and flash.
+
+## Software development context
+
+Note that these three are often the same people at different times.
+
+### Professionals
+
+These are developers who work within established teams, who often have processes and procedures in place, sometimes imposed externally. These users sometimes have strict needs about branch workflows, linters and hooks, merging vs. rebasing, and mechanisms for tagging and releasing. We can serve these developers best by ensuring we have _maximum flexibility_ so they can fit our tooling to their existing processes with minimal fuss. Providing rich _extensibility_ also helps in these contexts, because it would allow teams to overlay complex workflows on top of our basic building blocks with internal packages and tools.
+
+### Open-source maintainers
+
+Other developers live in an open-source world, shepherding contributions from others, giving feedback, and merging or rejecting pull requests. Maintainers would appreciate features that allow them to _investigate and triage work_ across large sets of repositories and pull requests and _maintain situational awareness_.
+
+### Hobbyists
+
+Finally, users who tinker with personal projects in their free time should have _minimal friction_ to being able to set up and get code out. These users are likely to benefit from being able to work with little ceremony and few obstacles.