Github: Expose services for other packages to consume

[smashwilson]

This has been in my head for quite some time, but I just realized that I never actually filed the issue to capture it. To quote myself from the past:

For this package I personally prefer to keep our vocabulary as close to git's as possible, partially because one of my goals for it is for it to act as a tool for gently teaching git novices git concepts. The sync button is super handy, but it also conceals the operations it performs behind an abstraction that doesn't exist in other clients or on the command-line. If a developer first encounters git with this package, but is able to follow instructions written for general git users in an open-source project's contributing guide, I'll be very happy.

Part of my Evil Plan ™️ for this package is to expose a variety of services that other packages can consume to overlay higher-level workflows on top of the basic operations provided directly. For example, you could install a package that adds useful commands and controls for GitHub flow, a different one for git flow, or even something homegrown for whatever bespoke git branching models are used in some internal project. To me, that's where compound actions like "sync" would live.

I can see several "layers" of services which would be useful to provide:

1. Raw git operations. Allow other packages to execute arbitrary git commands by re-exporting our git process machinery. This will allow other packages to participate in our async queue and avoid all of the concurrency and performance gotchas that we've squashed over time.
2. Hooks into GitHub package features. For example, it would be neat to be able to interpose your own package's conflict resolution tooling or diff view.
3. High-level workflow operations. I'm picturing a service function per registry command as a rough target. This would enable packages to succinctly express workflow-level integrations without having to re-invent the wheel in terms of the best git porcelain for the "primitives".

[iolsen]

Hoping this will facilitate changes like this one: https://github.com/atom/atom/pull/14456

[BinaryMuse]

Based on the conversation in https://github.com/atom/atom/pull/14456, I'd like to do some more thinking about an MVP of this we could ship sooner rather than later (with a focus on the "M" but also the "V" :).

For the very short term, I'd like to focus on the following:

1. Atom core as a consumer — while the service will be exposed from the package for anyone to use, I think we should version it as v0.x.x and ensure that it's clear that this is a prerelease/pre-alpha version of the service and will definitely change. The goal is to allow us to move the Atom core features that rely on Git information over to using the GitHub package machinery, without dedicating to a specific interface for the long-term.
2. Expose core machinery — Overall, I like @smashwilson's points above for a long-term vision of the service. For now, I think we should focus on exposing lower-level machinery and see what kind of usage patterns emerge and how we might provide higher-level affordances in the future to enable them and others like them.
3. Ensure visibility into usage and performance — We've done a lot of work to ensure the GitHub package performance is as good as it can be. It would be pretty easy for a service consumer to negate all this hard work by behaving improperly — something as simple as over-eagerly running Git commands could fill up the queue and affect the performance of every other consumer, including the GitHub package. To help deal with this, I would like the entry-point to the service to be a function where a consumer registers with some identifier (e.g. "atom.gutter" or "atom.tree-view") in order to get an instance of the service so we can keep track of performance metrics and more easily diagnose root causes when people have issues.

Since this affects potentially a lot of things, I'm pinging @atom/core for 💭 s.

[nathansobo]

I love the idea of identifying the consumer. I almost wonder if this is something we could bake into the service framework itself, because it should know who is consuming what.

[nathansobo]

The goal is to allow us to move the Atom core features that rely on Git information over to using the GitHub package machinery, without dedicating to a specific interface for the long-term.

If you put it out there and people start relying on it, we should at least attempt to maintain the old interface as we evolve by continuing to expose shims for the older versions.

[smashwilson]

I love the idea of identifying the consumer. I almost wonder if this is something we could bake into the service framework itself, because it should know who is consuming what.

I like this idea. In general, having the ability to identify the name of the package calling an Atom method would be really useful. I've thought about using this to build an atom.log() service that lets you filter and set verbosity per package, for example.

I have a vague idea about how to implement this... if I get a chance, maybe I'll throw a PR together that lets us do this.

[nathansobo]

I have a vague idea about how to implement this

I've thought about capturing a stack trace but there is overhead. Curious to see what you come up with.

[nathansobo]

Right now I'm in a situation where I want to detect whether a file is ignored. Would be nice to have this service.