Write the Initiatives Plugin

[decentralion]

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.

Status: In progress

---

The plugin has been merged into master!

The remaining steps are to start using it for the SourceCred instance, and create a versioned release of the SourceCred code including this plugin. See Release v0.5.0 .

Champion^?:

---

@Beanow

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.

Dependencies:

---

• SourceCred core plugin system
• WeightedGraph; Enable plugins to set weights
• Refactoring the load system
• Unified reference detection

References:

---

• The initiatives category descriptions and template
• What does and does not count as an Initiative
• Supernodes: Moving past raw activity

Contributions:

---

Early work

• Implementation thoughts post
• Initiatives: create plugin declaration
• Initiatives: define internal datatype Initiative
• Initiatives: implement basic createGraph

Discourse-based tracker

• Implement Discourse initiative tracker parsing.
• Initiatives: implement “cooked HTML” template parsing
• Initiatives: create Initiative from discourse topics
• Initiatives: implement DiscourseInitiativeRepository

File-based tracker

• RFC: change Initiatives plugin to be file-based instead of Discourse-based
• Initiatives: add initiativesMap type
• Initiatives: add conversion functions for InitiativesMap
• Add InitiativesDirectory and InitiativeFile types
• Initiatives: create and parse InitiativeFile addresses
• Initiatives: validate and read files from local directory
• Initiatives: create InitiativeId concept
• Initiatives: replace trackers with InitiativeIds
• Initiatives: implement conversion from InitiativeFiles
• Initiatives: implement loadDirectory
• Initiatives: add URLs to remote files in node descriptions

Loading pipeline

• Initiatives: add Project parameters
• Initiatives: pass SOURCECRED_INITIATIVES_DIRECTORY to LoadContext
• Initiatives: implement loader

Enhancements

• Initiatives: define weights to allow Cred minting

Releasing

• Release v0.5.0

[Beanow]

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.

[decentralion]

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.

[Beanow]

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?

[Beanow]

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)

[decentralion]

Does that seem right?

Yep, that seems right.

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)

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

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.

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).

So perhaps a fell short champion may lose some cred by flowing it to the initiative node.

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.

[Beanow]

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

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.

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).

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.

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.

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?

[burrrata]

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

[Beanow]

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.

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.

[s_ben]

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

[burrrata]

Not really. I just think this is fun

[burrrata]

Can we add the Initiatives plugin folder to this Initaitive, or are only PRs scored? Also, when this turns into an Artifact would we add the Initiative Plugin folder as a contribution?

[decentralion]

Can we add the Initiatives plugin folder to this Initaitive, or are only PRs scored?

Currently directories don’t exist in the graph. @wchargin have spent a while talking about how we could have a “directory plugin” which treats git directories as graph nodes, connects them to PRs which modify directory contents, etc. However, there are challenging problems around how to identify directories across revisions and renames, and we never prioritized this area of research, so we are still pretty far from having such a plugin. (Could be a good initiative to track. Will eventually be quite valuable.)

Also, when this turns into an Artifact would we add the Initiative Plugin folder as a contribution?

Yeah, once we have the aforementioned directory plugin, that would make a lot of sense.

[burrrata]

Created an Initiatives Wish List item: GitHub Directory Plugin

[Beanow]

Simplified the dependencies to:

• SourceCred core plugin system
• Refactoring the load system
• Unified reference detection

UniRef already depends on the underlying github/discourse detectors. And we no longer depend on the Discourse refactor to load Initiatives from (as we moved to file-based).

[Beanow]

Categorized and included new contributions.

[Beanow]

• Updated the status!

@beanow

The plugin has been merged into master !

The remaining steps are to start using it for the SourceCred instance, and create a versioned release of the SourceCred code including this plugin. See Release v0.5.0 .

• Added Release v0.5.0 as a contribution.
• Updated this wiki’s style to more closely match some of my others.