Distinguish between library services and delegate services.md

Library vs delegate services

Motivation

Packages may need another package as a library (i.e. a consumer may depend on a specific provider package, see atom/service-hub#6). We should distinguish between that type of service (library) from the type of service commonly being used by current packages (delegate).

Library service examples:

• A dialog UI component provided to other packages for building custom dialog boxes (e.g. an authentication dialog for connecting to remote file servers)
• A text editor mouse-move listener provided to other packages that emits an event every time the mouse moves over a new word (e.g. for implementing jump-to-definition)
• ...

Delegate service examples:

• An autocomplete UI that consumes delegates for finding completions to suggest
• A linter UI that consumes delegates for finding language-specific warnings and errors
• ...

Library consumers currently break if the provider package isn't activated -- particularly for tests, which don't activate any packages by default. By distinguishing them from delegate consumers, Atom can activate library dependencies before activating a package or keep the package deactivated if the dependencies aren't installed (or perhaps apm install them?).

Proposed "package.json" entries

Libraries allow 3rd parties to reuse code

A library that provides a dialog UI component for other packages to use:

"libraries": {
  "providers": {
    "dialog-component": {
      "description": "A base component for creating dialog boxes",
      "versions": {
        "1.0.0": "getDialogComponent",
        "0.58.0": "getLegacyDialogComponent"
      }
    }
  }
}

A client of the library that shows a dialog for logging into remote file servers:

"libraries": {
  "consumers": {
    "dialog-component": {
      // This marks the Atom package dependency.
      "package": "my-dialog-component",
      "versions": {
        "^1.0.0": "setDialogComponent",
      }
    }
  }
}

Then the promise-based API atom/service-hub#6 could look like:

var promise = global.libraries.consume('dialog-component', '1.0.0');

Delegates allow 3rd parties to add extensions

These would look pretty much the same as the current "services" API.

An autocomplete UI shell that shows completions provided by delegates:

"delegates": {
  "consumers": {
    "autocomplete": {
      "versions": {
        "^1.0.0": "addAutocompleteDelegate",
      }
    }
  }
}

An autocomplete provider that suggests Objective-C completions:

"delegates": {
  "providers": {
    "autocomplete": {
      "description": "Add support for Objective-C autocomplete",
      "versions": {
        "1.0.0": "getObjectiveCAutocompleteDelegate",
        "0.58.0": "getLegacyObjectiveCAutocompleteDelegate"
      }
    }
  }
}