Identity: add user documentation to README (#1735)

By adding information about configuration and what identity contractions
do, it provides more reference for instance maintainers and community
members to understand the plugin.

Includes rephrasing and feedback from @s-ben and @vsoch.

Closes #1725

src/plugins/identity/README.md

@@ -1,19 +1,144 @@
 # SourceCred Identity Plugin
 
-This folder contains the Identity plugin. Unlike most other plugins, the
-Identity plugin does not add any new contributions to the graph. Instead, it
-allows collapsing different user accounts together into a shared 'identity'
-node.
+Unlike most other plugins, the Identity plugin does not add any new
+contributions to the graph. Instead, it's goal is to combine different user
+accounts into a single identity. For example, if a contributor has an account
+on both GitHub and Discourse (potentially with different usernames on each),
+the identity plugin can combine these two accounts into a single identity,
+allowing SourceCred to properly compute the Cred for this identity.
 
-To see why this is valuable, imagine that a contributor has an account on both
-GitHub and Discourse (potentially with a different username on each service).
-We would like to combine these two identities together, so that we can
-represent that user's combined cred properly. The Identity plugin enables this.
+The technical term for how we do such combining is a _contraction_. Which we'll
+use for the rest of this document.
 
-Specifically, the instance maintainer can provide a (locally unique) username
-for the user, along with a list of aliases the user is known by, e.g.
-`github/username` and `discourse/other_username`. The aliases are simple string
-representations, that are intended to be easy to maintain by hand in a
-configuration file. Then, the identity plugin will provide a list of
-`NodeContraction`s that can be used by `Graph.contractNodes` to combine the
-user identities as described.
+## Status and Caveats
+
+The Identity plugin currently only applies to new WeightedGraphs and Cred
+scores being generated. However, if you're using this data to distribute
+Grain or other tokens, you may need to contract the identities again.
+
+For example, someone might have received Grain in the past for their GitHub and
+Discourse user respectively, creating 2 separate accounts in the Grain ledger.
+After these GitHub and Discourse nodes were contracted to one identity node,
+the ledger would now have 3 separate accounts. The GitHub and Discourse ones
+holding past distributions, but no longer receiving more. And a new identity
+one which will receive distributions going forward. Normally you'd want to
+have just 1 account instead which holds all distributions including past ones.
+
+Code-reviewed support for Grain built into SourceCred should handle this in
+the future. But for now, requires the instance maintainer to handle Grain
+account contraction.
+
+## Configuration
+
+Identities can be configured using the `project.json` file.
+By adding entries to the the `identities` array.
+
+Below is an example `project.json` file which defines two identities, "User-A"
+and "User-B", contracting their respective GitHub and Discourse accounts.
+
+```js
+[
+  {
+    "type": "sourcecred/project",
+    "version": "0.4.0",
+  },
+  {
+    // The identities we should contract.
+    "identities": [
+      {
+        "username": "User-A",
+        "aliases": ["github/user-a", "discourse/user-a"],
+      },
+      {
+        "username": "User-B",
+        "aliases": ["github/user-b", "discourse/user-b"],
+      },
+    ],
+
+    "id": "@example-project",
+    "discourseServer": {
+      // ...
+    },
+    "repoIds": [
+      // ...
+    ],
+  },
+]
+```
+
+### Username
+
+The `username` field allows you to choose a new username for the contracted
+identity.
+
+It's case-sensitive, must be _unique in this project_ and can contain `A-Z`,
+`a-z`, `0-9`, `-` or `_` as valid characters.
+
+For display purposes the username is prefixed with an `@`.
+If a username is prefixed with `@` in the project file, it will be ignored.
+Meaning `"username": "User-A"` and `"username": "@User-A"` are equivalent.
+
+### Aliases
+
+Aliases are strings with a format of: `{plugin}/{user ID for this plugin}`
+Currently supported plugins are:
+
+| Plugin    | Example alias            | Notes                                                              |
+|:----------|:-------------------------|:-------------------------------------------------------------------|
+| GitHub    | `github/example-user`    | A user account on GitHub's platform.                               |
+| Discourse | `discourse/example-user` | A user account on the Discourse server configured in this project. |
+
+## How a contraction works
+
+Here is a simplified illustration of how contracting works under the hood.
+
+Note that contractions are done _after_ the plugins have created their
+respective parts of the graph. But _before_ any Cred scores are calculated.
+
+Let’s assume we have a user `abc`, who has both GitHub and Discourse accounts
+which we want to contract.
+
+The GitHub and Discourse plugins have mapped out the contributions, users and
+edges as they exist on those services. Even though we merge this into a single
+graph, the GitHub and Discourse contributions of the _same person_ are still
+disconnected.
+
+```
+GitHub user @abc
+├── authored Pull Request #123
+└── authored Issue #456
+
+Discourse user /u/abc
+├── authored Post /t/123/1
+└── authored Post /t/123/2
+```
+
+Using the information from the project file, the plugin creates a new Identity
+node and removes the alias nodes.
+
+```
+Identity @abc
+
+[REMOVED]
+├── authored Pull Request #123
+└── authored Issue #456
+
+[REMOVED]
+├── authored Post /t/123/1
+└── authored Post /t/123/2
+```
+
+Then the edges that were connected to the alias nodes are connected to the new
+identity node instead.
+
+```
+Identity @abc
+├── authored Pull Request #123
+├── authored Issue #456
+├── authored Post /t/123/1
+└── authored Post /t/123/2
+```
+
+The disconnect between the GitHub and Discourse service is now gone. If we now
+run the SourceCred algorithm, user `@abc`'s Cred will flow to a single node and
+produce a much more accurate Cred score than before.