# Write the Initiatives Plugin **URL:** \ **Category:** Initiatives\ **Tags:** 🏗️in-progress\ **Created:** [October 6, 2019, 2:41am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269 "2019-10-06T02:41:24Z")\ **Posts on this page:** 17\ **Page:** 1

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [October 6, 2019, 2:41am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/1 "2019-10-06T02:41:24Z")

# 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 🚀](https://github.com/sourcecred/sourcecred/issues/1679). # Champion[?](https://discourse.sourcecred.io/t/about-champions-and-heroes/291): * * * ![Avatar Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/45/98_2.png "Beanow") @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](https://discourse.sourcecred.io/t/weightedgraph-enable-plugins-to-set-weights/664) - [Refactoring the load system](https://discourse.sourcecred.io/t/refactoring-the-load-system/629) - [Unified reference detection](https://discourse.sourcecred.io/t/unified-reference-detection/301) # References: * * * - [The initiatives category descriptions and template](https://discourse.sourcecred.io/t/about-the-initiatives-category/242/1) - [What does and does not count as an Initiative](https://discourse.sourcecred.io/t/what-does-and-does-not-count-as-an-initiative/463) - [Supernodes: Moving past raw activity](https://discourse.sourcecred.io/t/supernodes-moving-past-raw-activity/340) # Contributions: * * * **Early work** - [Implementation thoughts post](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/3) - [Initiatives: create plugin declaration](https://github.com/sourcecred/sourcecred/pull/1416) - [Initiatives: define internal datatype Initiative](https://github.com/sourcecred/sourcecred/pull/1417) - [Initiatives: implement basic createGraph](https://github.com/sourcecred/sourcecred/pull/1477) **Discourse-based tracker** - ~~[Implement Discourse initiative tracker parsing.](https://github.com/sourcecred/sourcecred/pull/1418)~~ - [Initiatives: implement “cooked HTML” template parsing](https://github.com/sourcecred/sourcecred/pull/1478) - [Initiatives: create Initiative from discourse topics](https://github.com/sourcecred/sourcecred/pull/1480) - [Initiatives: implement DiscourseInitiativeRepository](https://github.com/sourcecred/sourcecred/pull/1483) **File-based tracker** - [RFC: change Initiatives plugin to be file-based instead of Discourse-based](https://discourse.sourcecred.io/t/rfc-change-initiatives-plugin-to-be-file-based-instead-of-discourse-based/576) - ~~[Initiatives: add initiativesMap type](https://github.com/sourcecred/sourcecred/pull/1638)~~ - ~~[Initiatives: add conversion functions for InitiativesMap](https://github.com/sourcecred/sourcecred/pull/1639)~~ - [Add InitiativesDirectory and InitiativeFile types](https://github.com/sourcecred/sourcecred/pull/1641) - [Initiatives: create and parse InitiativeFile addresses](https://github.com/sourcecred/sourcecred/pull/1643) - [Initiatives: validate and read files from local directory](https://github.com/sourcecred/sourcecred/pull/1644) - [Initiatives: create InitiativeId concept](https://github.com/sourcecred/sourcecred/pull/1646) - [Initiatives: replace trackers with InitiativeIds](https://github.com/sourcecred/sourcecred/pull/1647) - [Initiatives: implement conversion from InitiativeFiles](https://github.com/sourcecred/sourcecred/pull/1648) - [Initiatives: implement loadDirectory](https://github.com/sourcecred/sourcecred/pull/1649) - [Initiatives: add URLs to remote files in node descriptions](https://github.com/sourcecred/sourcecred/pull/1670) **Loading pipeline** - [Initiatives: add Project parameters](https://github.com/sourcecred/sourcecred/pull/1671) - [Initiatives: pass SOURCECRED\_INITIATIVES\_DIRECTORY to LoadContext](https://github.com/sourcecred/sourcecred/pull/1672) - [Initiatives: implement loader](https://github.com/sourcecred/sourcecred/pull/1675) **Enhancements** - [Initiatives: define weights to allow Cred minting](https://github.com/sourcecred/sourcecred/pull/1674) **Releasing** - [Release v0.5.0 🚀](https://github.com/sourcecred/sourcecred/issues/1679) ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [October 17, 2019, 10:10pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/2 "2019-10-17T22:10:27Z")

Having a chat with @decentralion just now, decided I will be [championing](https://discourse.sourcecred.io/t/about-champions-and-heroes/291) this [initiative](https://discourse.sourcecred.io/t/about-the-initiatives-category/242). 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. ---

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [October 17, 2019, 11:15pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/3 "2019-10-17T23:15:45Z")

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](https://github.com/sourcecred/sourcecred/tree/e043347526be83ab1d696387dab7db18ae172018/src/plugins/discourse) is a good reference case. - A plugin consists of a few vital pieces: - 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: - 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](https://github.com/sourcecred/sourcecred/blob/e043347526be83ab1d696387dab7db18ae172018/src/core/project.js#L26-L34). Since we’re going [Deep then Wide](https://discourse.sourcecred.io/t/deep-then-wide/102), 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](https://github.com/sourcecred/sourcecred/blob/e043347526be83ab1d696387dab7db18ae172018/src/api/load.js#L43) to use the new plugin information. - Once we do this, we can start leveraging the initiatives system, by starting in on [cred bounties](https://discourse.sourcecred.io/t/enable-cred-bounties/257). 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. 🙂 ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [October 18, 2019, 9:10am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/4 "2019-10-18T09:10:45Z")

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? ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [October 18, 2019, 10:43am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/5 "2019-10-18T10:43:36Z")

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](https://github.com/sourcecred/sourcecred/issues/1049)) ---

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [October 18, 2019, 3:23pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/6 "2019-10-18T15:23:08Z")

> [@Beanow](#): > > Does that seem right? Yep, that seems right. > [@Beanow](#): > > 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. > [@Beanow](#): > > 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). > [@Beanow](#): > > 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](https://discourse.sourcecred.io/t/about-champions-and-heroes/291/7). ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [October 19, 2019, 10:50am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/7 "2019-10-19T10:50:07Z")

> [@decentralion](#): > > 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. > [@decentralion](#): > > 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. > [@decentralion](#): > > 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? ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [October 21, 2019, 3:00am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/8 "2019-10-21T03:00:54Z")

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

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [December 3, 2019, 8:00pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/9 "2019-12-03T20:00:15Z")

**Status update** With [Discourse mirror revision](https://discourse.sourcecred.io/t/discourse-mirror-revision/365) / [#1426](https://github.com/sourcecred/sourcecred/issues/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. ---

**Author:** ![s\_ben](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/s_ben/32/816_2.png) [@s\_ben](https://discourse.sourcecred.io/u/s_ben)\ **Post date:** [December 3, 2019, 8:16pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/10 "2019-12-03T20:16:16Z")

You do have some [firepower](https://observablehq.com/@decentralion/credsperiment-week-10) now, so are moving non-trivial cred-\>Grain-\>$ with each ❤. Is that influencing your engagement? ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 22, 2019, 4:04am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/11 "2019-12-22T04:04:11Z")

Not really. I just think this is fun 🙂 ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 27, 2019, 7:34pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/12 "2019-12-27T19:34:07Z")

Can we add the [Initiatives plugin folder](https://github.com/sourcecred/sourcecred/tree/master/src/plugins/initiatives) to this Initaitive, or are only PRs scored? Also, when this turns into an [Artifact](https://discourse.sourcecred.io/t/about-the-artifacts-category/253) would we add the Initiative Plugin folder as a contribution? ---

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [December 28, 2019, 1:02am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/13 "2019-12-28T01:02:02Z")

> [@burrrata](#): > > Can we add the [Initiatives plugin folder](https://github.com/sourcecred/sourcecred/tree/master/src/plugins/initiatives) 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.) > [@burrrata](#): > > Also, when this turns into an [Artifact](https://discourse.sourcecred.io/t/about-the-artifacts-category/253) 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. ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 28, 2019, 3:08am UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/14 "2019-12-28T03:08:10Z")

Created an Initiatives Wish List item: [GitHub Directory Plugin](https://discourse.sourcecred.io/t/github-directory-plugin/506/2) ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [February 28, 2020, 1:05pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/15 "2020-02-28T13:05:46Z")

Simplified the dependencies to: - SourceCred core plugin system - [Refactoring the load system](https://discourse.sourcecred.io/t/refactoring-the-load-system/629) - [Unified reference detection](https://discourse.sourcecred.io/t/unified-reference-detection/301) 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). ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [February 28, 2020, 1:07pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/16 "2020-02-28T13:07:25Z")

Categorized and included new contributions. ---

**Author:** ![Beanow](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/beanow/32/98_2.png) [@Beanow](https://discourse.sourcecred.io/u/Beanow)\ **Post date:** [February 29, 2020, 2:09pm UTC](https://discourse.sourcecred.io/t/write-the-initiatives-plugin/269/17 "2020-02-29T14:09:40Z")

- 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 🚀](https://github.com/sourcecred/sourcecred/issues/1679). - Added [Release v0.5.0 🚀](https://github.com/sourcecred/sourcecred/issues/1679) as a contribution. - Updated this wiki’s style to more closely match some of my others.