Odyssey Hackathon Design Doc

[BrianLitwin]

Team: Feel free to edit this doc and expand on it in the comments

Concept: Manual-mode SourceCred. Give users more control over the flow of Cred by letting them create nodes and edges. Give users (and non-coders) agency to determine which contributions are important and letting them customize how SourceCred supports the values of their community.

Frontend

Manual Mode Editor

• General Idea: Give users a way to create their own nodes and edges and integrate these with the Git/GitHub-derived SourceCred graph

Main Components

• A Graph Pane, like: Graph Layout Example, with two side panes, a Node Pane and an Edge Pane
• It would be good to go into the hack w/ a wireframe/layout doc so that everybody's on the same page

Node Pane

• Provides info on the currently selected node
• Lets users create new nodes

Edge Pane

• Lets users create edges to other nodes
• You can add edges to both visible and invisible notes

Search Functionality

• Lets users look up nodes in the auto-generated SourceCred graph that are "invisible"
• Nodes are visible or invisible based on whether they comprise part of the current manual-mode graph

Weight Config

• Give users control of how to weight these manually-created nodes/edges?

Tools

• Use d3 to get this off the ground
• React.js?

Questions
How to connect to auto-generated SC graph? (probably by connecting the manually-created nodes to their relevant repo nodes)

Backend

• Keep it simple, save to disk
• What to use?
• Use SourceCred data files as the data format
• Save graphs to .json
• Flow the manually created scaffold into the rest of the project

Research Backend

• @mz creates a bunch of cool demo cases that show off the social impact and reach of this technology, and then we import them into frontend

Tools

• Python + Jupyter Notebooks

Create synthetic example cases

• throwing a a party
• producing a 3d printed design
• having a hackathon team
• Use it on sourceCred
• Perhaps get some other teams to use it

Narrative

• Distill all the wonderful ways SourceCred could improve the world into one compelling vision for the hack, and tie it into the tech we're working on.
• Manual-mode will make SourceCred a tool to empower non-coders alongside coders; provide more transparency and options to customize SourceCred to meet the needs of diverse communities.

[teamdandelion]

I imagine the data model for the new plugin will look something like:

type ManualNode = {|
  // Maybe hacky -- do we want to keep enshrining the RepoId concept even
  // though it is pretty tied to GitHub right now? Definitely most convenient
  // for now, though.
  +repoId: RepoId,

  // Must be unique within the scope of the RepoId.
  // maybe just incrementing numeric IDs?
  +id: string,

  // human readable name
  +name: string,

  // human readable description (md supported)
  +description: string,

  +weight: number,
|}

type ManualEdge = {|
  // Maybe hacky -- do we want to keep enshrining the RepoId concept even
  // though it is pretty tied to GitHub right now? Definitely most convenient
  // for now, though.
  +repoId: RepoId,

  // Must be unique within the scope of the RepoId.
  // maybe just incrementing numeric IDs?
  +id: string,
  +src: NodeAddressT,
  +dst: NodeAddressT,

  // human readable name
  // Do we want this? might be cumbersome to need to 
  // write a name for every edge. maybe make it optional,
  // or make it type-based with a few default types?
  +name: string,

  // human readable description (md supported)
  // I have commented this out b.c. i think having descriptions
  // for each edge might be a bit much. Maybe make it optional though.
  // For certain important edges having a description could be nice.
  // Would probably only be visible in the "edge editor" panel
  // (writing it on the graph display directly would be too much noise)
  // +description: string,

  +toWeight: number,
  +froWeight: number,
|}

type ManualPluginData = {|
  +nodes: ManualNode[],
  +edges: ManualEdge[],
|}

[teamdandelion]

Btw, take a look at notes on the Artifact System. I basically want to use the manual plugin to create the artifact system for SC. So we can come up with a map of all the major "pieces" of SC and then link those pieces either to PR and issues (e.g. for pieces "build", "testing", "graph", "github plugin") or to manual nodes (e.g. for pieces "project founding", "PR and outreach"). "Project management" would be kind of in-between, as some of it is happening via issues/PRs.

Manually editing all these connections in the editor would be a pain. So I think we should take the opportunity to add support for GH labels, and then link it up so that we can make a connection from artifacts to everything that has the matching label? It's also kind of a hack, but would make it easier to make these assignments from within GitHub.

[teamdandelion]

That said, the number of PRs in this project's history is small enough that with a bit of effort, we could go and link every PR to the appropriate artifact(s). I believe this would enormously improve the cred quality.

[teamdandelion]

Thinking about the UI a bit more: there are some interesting nuances here.

• For the graph visualizer: it depends on having a scored PagerankGraph (so that we can size nodes by score, and display the scores)
• For the manual mode editor: if we want to be able to select GitHub issues/PRs to link by title text, then we have a dependency on the GitHub ExplorerAdapter (to get node descriptions for searching)

That said, for purposes of the hack, IMO we don't need the GitHub integration. That's a P2 b.c. its mostly relevant for linking in real world data, not needed for producing clean, digestible explorations of what SC is all about. From an architectural standpoint, I think that the graph visualizer and the manual mode editor should be decoupled.

Manual mode editor is 1 component (composed of node pane, edge pane) which generates the manual mode graph data structure.

Graph visualizer is another component which takes in a PagerankGraph, and a visibility filter (maybe implemented as a fn(), maybe implemented as a set of visible nodes). Then we can write a containing component that links together the visualizer and the editor.

But this gives us a lot of flexibility, in that we can take the same visualizer and drop it into the main SC UI for showing high-cred nodes and their interconnections.

[teamdandelion]

Here are some crappy mockups of how the frontend could look:

Note the UI doesn't have a way to add new nodes and edges, just edit them, right now. But we need affordances for adding. I'm thinking maybe a material-design-style (+) sign in the lower right hand corner that lets you add a node or edge. Adding a node should be quite simple: a new "blank" node is created and immediately selected, so the user can then use the editor to populate its fields. But adding a new edge is a little tricker, as the edge needs to have src/dst populated, and I'm not sure what the modality should be for selecting the src and the dst. For the initial prototype maybe we should do it through point-and-click interactions, but once we want to be able to link into content from GitHub (which will be default hidden to avoid overloading the visualizer) that will be tricky.