SourceCred

Write the Initiatives Plugin

#1

Write the Initiatives Plugin

Status: In progress

Champion?:

Avatar Beanow @Beanow

Initiative Description:

We now have an initiatives category on Discourse (this one). However, SourceCred isn’t yet aware of it, so Initiatives don’t yet flow any special cred. We should add initiatives directly to the SourceCred graph.

Benefits:

Initiatives will add a layer of interpretability and robustness to the SourceCred graph. They are more interpretable (vs. pull requests where it can be hard to parse their impact or significance). They can also be used for different styles of cred minting, grain boosting and/or bounties.

Implementation plan:

The rough outline of necessary steps is.

  • Get necessary (missing) information from Discourse API using the Discourse plugin and expose it.
  • Create the initiatives plugin from scratch, to initially detect initiatives and model it into the graph.
  • Wire it up with configuration and into the load command.
  • Iterate on this by adding bounty dynamics.

Concrete steps are:

  1. Define the nodes and edges we will add. PR #1416
  2. Define the intermediate datatypes the initiatives plugin will use to represent initiatives (and it’s dynamics). PR #1417
  3. Find out which data is missing from Discourse and obtain it.
  4. Expose the rich Discourse data to the incentives plugin.
  5. TBD…

Dependencies:

References:

Contributions:

3 Likes
CredSperiment Week 3 Distribution
Please help organize this Discourse!
Community Call (12/03/2019) - Notes & Recording
Some questions as a new comer
Some questions as a new comer
Community Call (11/26/2019) - Notes & Recording)
Week 5 Grain Distribution
About Champions and Heroes
Cred/Grain Dynamics
About the Initiatives category
Summary of planning chat
Cred/Grain Dynamics
Implement Cred Weighted Prioritization
Discourse Reference & Mention Detection
#2

Having a chat with @decentralion just now, decided I will be championing this initiative.

As it’s probably the more valuable technical initiative to make the CredSperiment better, giving it a high priority now.

By championing, I mean that I’ll be leading the process. Though to actually get things done I will still need help. Mostly @decentralion to get me up to speed with more SourceCred internals, great discussions and code reviews.

First steps I want to concentrate on:

  • Better scope out the work (sub-components needed, outline implementation).
  • Update the wiki to match.
  • Identify a good technical starting point to work on.
1 Like
#3

Super excited to have you championing this, @Beanow!

Here are some implementation thoughts:

  • We’ll want to add a new, lightweight plugin. I the Discourse plugin is a good reference case.

  • A plugin consists of a few vital pieces:

    • A declaration (example) which provides new node and edge types. I think for now the only node type will be the Initiative node, and the edge types will include champions, references, has contribution, depends on.
    • A createGraph method (example). This will be responsible for actually creating a new subgraph containing information from the plugin, which is then merged with other plugin graphs.

  • Our existing plugins get data from an external source (e.g. Discourse, GitHub, etc). This plugin will get data from another plugin–from the Discourse plugin. We currently don’t have any mechanism for cross plugin data dependencies. Eventually we should build clean APIs to handle this, for now I’m fine with something relatively hacky that gets the job done.

  • Once we’ve figured out how to expose the Discourse mirror:

    • We’ll need to update the Discourse plugin to store and provide category information. This will mean updating the fetching logic (e.g. adding category id here). Possibly we’ll want new APIs on the sqlite mirror.
    • We should be able to re-use logic from Discourse Reference Detection to parse the actual links, although we’ll need to add GitHub detection as well. (Adding GitHub reference detection to Discourse will likely make sense as its own initiative; I’d be fine to see the initiatives plugin merge without GitHub support, we can add it as a followon).
    • We can then have the Initiatives plugin parse all the topics within the Initiatives category, and generate an intermediate Initiatives data structure.
    • We can then transform the initiatives data structure to generate the Initiatives subgraph. We should think a bit about error handling, and how to accommodate changes to the schema, or incomplete initiatives.

  • The steps above should leave us with a working initiatives plugin, so we’ll just need to configure it. We have a fair bit of technical debt in how we configure plugin information, which you can see in the fact that plugin configurations accumulate in a single hardcoded project config. Since we’re going Deep then Wide, I think it’s not yet time to pay off this debt. So we can just update the Project config to store information about whether initiatives are getting used, what their CategoryId is, etc.

  • Then we can update api/load to use the new plugin information.

  • Once we do this, we can start leveraging the initiatives system, by starting in on cred bounties. Until then, as a hack we can give initiatives a high node weight, although this won’t be quite right–we want to unlock the cred when the initiative is completed, not when it is proposed.

If you think this post is a valuable contribution towards achieving the initiative, I suggest explicitly linking to this post as “Contribution” in the overall initiative wiki. A good way to reward the work of clearly documenting the context around achieving our goals. :slight_smile:

3 Likes
#4

Ha! Your enthusiasm is showing. Thank you for a greatly detailed post. I will be incorporating this in my own words in the wiki’s implementation plan. But to check with you, I think the coarse breakdown is:

  • Get necessary (missing) information from Discourse API using the Discourse plugin and expose it.
  • Create the initiatives plugin from scratch, to initially detect initiatives and model it into the graph.
  • Wire it up with configuration and into the load command.
  • Iterate on this by adding bounty dynamics.

Does that seem right?

If so, either getting more information or starting on the plugin (using unit tests to stub the discourse data dependencies) seems like the logical starting point.

Something I will need pretty soon is an API key for our Discourse / test environment which seems to be an admin only thing. Can you set me up with those @decentralion?

2 Likes
#5

Some thought on the life cycle of initiatives and it’s graph.

Currently I think we should leave initiatives untouched when it comes to it being a discourse topic. However it should create a new node (assuming it’s correctly formatted) “Initiative” which has an edge to the topic it’s based on (maybe with edge weight: 0) and use the special template to add the rest of it’s edges.

More importantly. I think is initiatives are stateful.

  • Whether the initiative has been completed or not.
  • The cred/grain bounty that accumulates / releases.
  • Self-proclaimed champions vs champions that followed through or fell short in retrospect.

Right now the simplest approach I can think of, is to use the wiki aspect to track this state, and only implement flowing cred in retrospect. So an initiative that’s not yet completed, could create nodes and edges, but they’re all 0 weight. Once it’s been completed, it will act as a seed to flow it’s bounty.

In a way, I think the different status a champion can have (self-proclaimed, actual, fell short) can be different edge types. And might flow cred accordingly. So perhaps a fell short champion may lose some cred by flowing it to the initiative node. Another approach would be to always have an inbound and outbound edge for champions. So there’s always a staking of cred and a return of cred edge. Setting it’s weights can then be used to control flow according to their status. This may be more flexible, but a little more tricky to show in a UI what it means.

Something along the lines of:

  • staking cred edge = completed ? weight : 0
  • return cred edge = completed && championed by this user ? weight : 0

Instead of edge weight 0, the presence or absence of edges can be used as well. So for instance:

  • Completed initiative
    • Inbound champion edge from Alice
    • Inbound champion edge from Bob
    • Outbound champion edge to Alice
  • Incomplete initiative
    • Inbound champion edge from Alice

Means Bob is the fell short champion type and Alice the actual type. Alice is also the self-proclaimed type on the incomplete initiative.

Edit: the declaration.js file always writes edges as being bi-directional. So the first approach of using the weight values makes more sense. (Relates to https://github.com/sourcecred/sourcecred/issues/1049)

1 Like
#6

Yep, that seems right.

That makes sense to me. We could think of the initiative topic itself as being a ‘contribution’ towards the initiative, with a contribution edge.

Yeah, I agree re: using the wiki to track the state. It’s also good as it allows retroactive addition of more contributions to the initiative (whether b.c. they were overlooked initially, or because the initiative wound up needing more work).

I don’t think the edges should be zero weight; an initiative can flow some cred before it is completed. However, it won’t mint any new cred until it’s completed. For example, if I reference an initiative, I flow some cred to it; its reasonable that the cred then flows to people who have been working on the initiative so far. Once the initiative is finished, then a lot more cred is minted, and seeded at the initiative (in current terminology, the initiative’s node weight increases from 0 to, say, 100).

I caution against thinking of cred this way. Depending on the topology of the graph, creating a new edge from the champion to the initiative node could result in the champion’s cred decreasing or increasing. For example, suppose all of the champion’s existing edges point to flow cred to a “black hole” node called Foo. None of that cred recycles back to the champion. Then if the champion creates a new edge pointing to the initiative, since the champion is connected to the initiative, some of that cred recycles back to the champion, which means the champion’s cred increases.

I propose we start with the simplest system: all the edges have fixed type-level weights (like other edges in the graph). If a champion fails, they get removed from the wiki post (possibly replaced by someone else). So that will handle the “absentee” or “failed” champion–they just lose champion status. We can leave out any penalties for failed champions, and handle that when we implement grain staking for champions.

2 Likes
#7

I wonder about that. As I feel like explicit contribution links imply a subjective usefulness and relevance judgement. While I can certainly imagine a lot of useful and relevant conversation sparking on the initiatives’ topics, making that assumption by default feels like convention. And might even take the incentive out of doing so (since a low effort thread would be marked as a contribution anyway).

Your idea of using a particular post in the thread as references. Or alternatively explicitly “upgrading” the thread from just initiatives infrastructure to a contribution makes sense to me as a subjective evaluation.

Good point. As a much talked about work-in-progress in a social reputation intuitively would get cred (with me anyway). So I’ll go with the idea of edge weights being already set, but we’ll gate the minting of the bounty it has.

Not sure I understood this. A node can either increase or decrease in cred when it has a new outbound edge with a weight and a return edge with 0 weight, depending on what other nodes it’s connected to?

1 Like
#8

Since we don’t have boosting yet, I’m just going to like every post in this thread as a way to support this initiative lol

#9

Status update

With Discourse mirror revision / #1426 now wrapped up, my development attention will go back to the initiatives plugin.

Note these improvements include the “Get necessary (missing) information from Discourse API” step. So that is now done. :smiley:

The first thing I’ll be working from now is to add Initiatives to the graph. It would be a pretty bare-bones version without cred bounties or universal reference detection. From there I’ll add in the improvements.

2 Likes
#10

You do have some firepower now, so are moving non-trivial cred->Grain->$ with each :heart:. Is that influencing your engagement?