Open BrianLitwin opened 5 years ago
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[],
|}
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.
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.
Thinking about the UI a bit more: there are some interesting nuances here.
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.
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.
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
Main Components
Node Pane
Edge Pane
Search Functionality
Weight Config
Tools
Questions How to connect to auto-generated SC graph? (probably by connecting the manually-created nodes to their relevant repo nodes)
Backend
Research Backend
Tools
Create synthetic example cases
Narrative