RFC: change Initiatives plugin to be file-based instead of Discourse-based

1

In line with the review culture, I would like to open up this change for review and comments here.

So far, the design for Write the Initiatives Plugin, has been to use Discourse as the data source, by making the first post a wiki and parsing it’s special template so that can be graph nodes.

The proposed change (initially suggested by @decentralion) is that we use the Discourse topics for proposing and discussing an Initiative. But in order to include it in the graph, we use a configuration file on GitHub.

Benefits:

  • Less error prone.
    Because these files can be validated and no special templates are required in the forums.
  • Changes to an Initiative can be reviewed.
    Using a GitHub PRs workflow instead of Wiki’s.
  • Removes Discourse dependency from Initiatives.
    Which may be important for other communities that don’t use Discourse.

Drawbacks:

  • Editing Initiatives is less easy.
    Compared to editing a Discourse wiki. We may want specialized editing tools for this.
  • GitHub access is not automatic.
    While editing wikis is a privilege you automatically gain with Discourse trust levels.
  • The topic may be inconsistent with the config file.
    If we keep using the template for the Discourse topics (champion, status, contributions, …) it may be out of date when comparing to the config file. Removing this information from the topic means we don’t have a nicely formatted page with the status to link to anymore.
  • Reference detection gets more complex
    As we don’t have one place to link to anymore, detecting references to an Initiative would be more tricky.
1 Like
2

cc @anon60584824 @s_ben, who chimed in on this topic in the community call.
Also want to ping @LB @burrrata for more thoughts on GitHub to be fully included community members.

3

My 2cts, I think the file-based system is pretty flexible. And we can create technical solutions for many of the drawbacks if needed.

  • Custom editor for the Initiatives config format.
  • Automatic pull request systems to make GitHub more accessible (@anon60584824 worked on one).
  • Custom Discourse plugin to include the most recent Initiative data in a topic.

etc…

However that takes some development time, so I think it’s important we find a mean-time solution that works for us without many special tools.

For example, I think it’s worth realizing, maintaining the GitHub repository requires very high trust as it directly impacts what happens to the payouts. Currently TBD @decentralion maintains our canonical cred instance. https://github.com/sourcecred/cred Compared to the wiki setup, this is much less permissionless.

Personally I’m OK with using this model, so long as there is consensus on that in the community :smile:

If not, similar to what I described in Discourse Admin trust model, maintaining the canonical cred instance requires very high trust. So I wouldn’t advocate for giving everyone merge rights. If this is something to address, a 2-out-of-3 approval process with high trust maintainers would be my suggestion.

TL;DR

I :+1: switching to config files.

5

This is a potentially very valuable feature. Version control/history is going to be important regardles. GitHub is the standard; this might make integrating with other tools easier down the line. Git itself is even more widely supported, and decentralized (even if GitHub censors a community, members have copies on their local machines - though actually that’s just commits I believe, not PRs…). There is a viable alternative in GitLab should GitHub become a baddie.

I know GitHub uses MarkDown, which would make creating docs that are similar to what we have in Discourse easier. MarkDown is also a widely supported format, which could make building a custom editor later easier…

I’m wondering what @burrrata thinks, as they know Discourse much better than I. Also, Aragon uses Discourse + GitHub in their Aragon Governance Proposal (AGP) process. Your proposal starts on Discourse, where the community gives feedback. Then if you have enough support, you create a PR on the AGP repo. Here’s a list of the current waiting PRs, https://github.com/aragon/AGPs/pulls

There’s a manditory 1 week community review on GitHub. Then the Aragon Association board reviews and gives final approval (or not), before putting it up for an on-chain vote. @burrrata please let me know if I’m butchering any of this. I’m also wondering if this is giving you flashbacks to problems Aragon has had. Do you think their ‘review culture’ is working well? Does it present barriers/bottlenecks?

6

I support shifting the initiatives plugin’s source of truth from Discourse to GitHub.

  • From a technical perspective, storing data in a programmatic and source-controlled format will be far easier than storing it in an ad hoc text format. When we want to make changes, atomically upgrading all the initiatives in a repository and concurrently bumping the version is far easier than trying to manually edit dozens or hundreds of Discourse wikis.
  • From a community management perspective, having changes to cred go through explicit review makes far more sense than a free-for-all where anyone can change the wiki and thereby change the cred flows. Needing a reviewer will help insure that we’re changing cred flows in an accountable, intentional, and consistent way.

I’d like us to think about the “alpha UI” by which we update the initiatives (and, in the future, artifacts). This is while we are doing it through manually creating GitHub pull requests, as opposed to having an explicit frontend.

The naive approach would have us directly propose changes to the json-serialized data, e.g. adding an initiative might look like inserting the following JSON blob into an array:

{
  "title": "my-initiative",
  "contributions": [
    ["sourcecred", "github", "sourcecred", "sourcecred", "PULL", "32"],
   ],
...
}

Needless to say this would be pretty miserable :slight_smile:. The raw SC address format was not selected for ease of manual entry, and hand updating JSON tends to be a mess. One could say, oh we should use yaml or such, but i think that’s a bandaid fix.

Riffing off a suggestion from @wchargin, I propose a js api instead. Something vaguely like:

const scRepo = new GithubRepoReferencer("sourcecred", "sourcecred");
const myInitiative  = new Initiative()
  .setTitle("my initiative")
  .addContribution(scRepo.pull(32))
7

@decentralion did you have a chance to look at the prototype I set up?

A JSON based or YAML based file using URLs and reference detection seem fairly intuitive as a step 1.

8

Ah, I hadn’t looked at your prototype yet. Using the URLs at the input layer makes good sense.

The yaml one is cleaner, though I’m hesitant to start depending on yaml… it adds another tech, and a google search for “yaml considered harmful” reveals that it’s no panacea.

I’d be fine starting with the JSON and using it long enough for us to learn what our common patterns are. Then when we’re properly frustrated with maintaining the JSON approach we can prototype the nextgen infrastructure.

Starting next week, I intend to have a weekly “cred review” cycle during which we discuss the week’s cred, and collectively propose tweaks and modifications. I expect that using the prototype initiatives plugin will be a big part of making this work. We’ll be using observable notebooks for this work, so it will also be easy to experiment in the notebooks with different ways of generating initiatives.

9

Please please please no yamls. I deal with enough YAMLs at work. They are a constant source of pain and subversion of expectations. https://noyaml.com/. If you need further convincing, let me know.

Keying the contributions by URL is a neat solution to improve the usability of manually making changes without having to encode the full address forms. It also adds a layer of encapsulation: URLs are logically human-facing and somewhat stable; node address formats need not be. I approve of this suggestion.

I’m open to a “builder-pattern” API like the one that @decentralion suggested, but I’d suggest starting with the plain data format first. If we see that it’s really painful to write, we’ll know what needs to be abstracted away, and can do so without introducing complexity before it’s needed.

10

Speaking of prototypes, testing the idea from the community call to use a built instance for this. https://beanow.github.io/sce/initiatives-discourse/timeline/@sourcecred/

This has 22 initiatives loaded from Discourse.

1 Like
11

Non-technical people don’t enjoy using GitHub, so they don’t. By using GitHub you will bias all engagement towards developers. Perhaps this is a feature? Perhaps it’s a bug? You decide.

Every time you use GitHub for anything non code related you create organizational debt. That debt compounds over time. Having a decision making process that spans multiple platforms adds to this debt. Having a decision making process that involves using a technical platform (GitHub) for non-technical contributors (forum community members) adds to this debt. Overall, it’s a road to ruin. I do not recommend trying to retrofit novel governance systems around legacy web2 infrastructure that was not designed for that use case.


Overall, I think this points to a higher level question: who is SourceCred for? Do we want to build SourceCred out as it’s own platform that can aggregate data from arbitrary APIs, or do we want to first customize SourceCred for a specific usecase with specific users on a specific platform. As is, there’s a real rift between non-technical contributors on Discourse and technical contributors on GitHub. The sooner this can be addressed the better.

1 Like
12

This is a valuable point to surface. It’s true that GitHub is a much more accessible and familiar platform for developers.

Part of our challenge is that at this stage in SourceCred’s life cycle, the project itself is much more accessible to developers. It’s a highly technical project, built around an undocumented variant of the PageRank algorithm. Folks who are already familiar with linear algebra, graph theory, and/or who can read the code itself will have a much easier time onboarding and contributing to the project. And, because so many of the project’s current bottlenecks are technical, developers also have a wider scope of contributions they can make.

This creates a dynamic which favors developers. This isn’t ideal, and isn’t where I want the project to be as it matures–but it also reflects our on-the-ground reality right now. The question I ask myself is: how can we acknowledge where we are today, and also grow the project in ways that make it more inclusive and accessible over time?

Sometimes, this will mean making tradeoffs in favor of shipping prototypes of features that may be less accessible, because we need those features in order to coordinate well enough to build the more accessible technology and accessible community. Having the alpha for the initiatives plugin live on GitHub is one of those tradeoffs.

I’d be interested to hear more about why you think this is the case. Do you think that GitHub’s workflows are uniquely poorly suited for non-code workflows? Or do you think that only coders are comfortable with GitHub, and the organizational debt comes from the way that using GitHub when not absolutely necessary skews who participates?

If the latter, what do you think of investing, as a community, in supporting our non-coder contributors in using GitHub effectively? It is a very powerful tool, whether it’s being used to store code, markdown documents, or any other kind of file.

We’ve been pretty clear that the alpha instance of initiatives is just that–an alpha–and that we will build a dedicated UI for initiatives, artifacts, and boosting that is accessible to SourceCred’s userbase at large. Given that this is explicitly a short-term decision, I feel that framing it as a “road to ruin” is unnecessary.

I ask you to give some thought to whether framing things in this way shines light on the discussion, or only makes it more heated.

We need infrastructure so that we can work together. Without infrastructure, we have no way to communicate, no way to coordinate, no way to share results, and no way to move forward as a community. Today, the infrastructure that works, and that we know how to use, is web2 infrastructure. If the future web3 governance systems were already ready for us, we wouldn’t need to do this work. :slight_smile:

The promise of the future is always built using the tools of the past. This means there’s a kernel of contradiction in any attempt to create a radical new system. I think we need to accept this contradiction, and do our best to manage it. To reject the tools entirely is to disempower ourselves.

SourceCred exists as a delicate interplay between short- and long-term goals.

In the long term, we want to design a fair and effective system for awarding credit, recognizing contributors, and distributing rewards.

In the short term, we want to hack together a system that works well enough to bootstrap the resources and labor we need to build that long-term system.

Both goals are vital. Without developing the long-term goal, we have no purpose. Without developing a viable short-term system, we have no way to achieve our purpose. However, these two goals are in tension with each other, and so we will need to make compromises along the way.

13

On Developer bias

Definitely agree with @burrrata and @decentralion on that it creates a stronger developer bias.

Even if it may be a perception difference, as @anon60584824 mentioned, signing up for an account and adding comments isn’t too different between these platforms. It’s still a real bias.

However I feel like this makes a lot of sense at this stage.

OSS as a natural fit

Like is being described in the manifesto drafts, open source is a niche where SourceCred can find the right environment to develop. It’s by no means the only place where it could apply.

Imo, the situation where Owners systematically exploit Workers and Resources is rampant everywhere. And they could all benefit from the premise of being recognized and rewarded more fairly. In the future I would be massively proud if SourceCred can make a difference for nurses, teachers, farmers, miners, nature, wildlife, and all those others currently undervalued and exploited.

But, we need a springboard that offers:

  • Open data
  • People who are already willing to work permissionlessly
  • Technical affinity to be able to grapple with graphs and game theory and algorithms
  • Funding

And focusing on OSS let’s us dogfood SourceCred.

So I think SourceCred v1 should be a tool / protocol that delivers on it’s promise in the Open-Source Sustainability space. And expand from there.

Users of a tool vs having an influence

One gotcha I think there is here, is that developing applications is very multi-disciplinary. SourceCred is no exception here. And I think GitHub doesn’t cater to all of these disciplines. Tools like GitHub / Bitbucket / you-name-it, in the teams I worked with are used by primarily developers and project managers (in a business setting). In my experience designers (usually), lawyers, business people, communications managers, rarely if ever touch a Git repository.

That doesn’t mean that the designs, business needs, market, copy, legal concerns have no effect on what gets merged in a Git repo. Heck if you’re a developer that disregards these, you’ll probably be out of a job soon.

It also doesn’t mean Git makes a bad tool for the task at hand. Just that other people on the team don’t use it directly. They’ll debate their wants and needs through different channels and ask the devs to make the changes to incorporate them.

We have several of these other channels in place as well. The changes in Git will be reflected in the canonical cred explorer, we have GitHub, Discourse, Discord, and soon CredCon (woo! :tada:) as places where you can get in touch and share concerns. I think this is absolutely critical to maintain. It’s much more important than finding a unicorn free-of-bias platform. This topic is a good (meta) example of that :]

So long as we maintain a culture and practice of broad inclusion, the properties of a particular medium become much less important for that inclusion.

Teaching people to use GitHub as @decentralion suggested, I think helps as well. But ultimately I think multiple channels is the way to go.

Technical notes

Aka, this is where I start nitpicking.

In that regard the Git part of GitHub is very much an improvement over Discourse. Git’s decentralized design has made it useful with and outlive many of the transport protocols. Whether you’re using USB sticks and sneakers to transport your repo’s, emailing commits, using a HTTP/web2 portal or want to store them on IPFS/Blockchains. Git has a track record to be an excellent fit for all of them.

I wish Discourse could fork and merge the way Git does. I’ve been considering a bounty for this.

that was not designed for that use case.

GitHub is exactly designed as the type of collaboration tool we’re looking for. When the choice is between Discourse and GitHub, it’s clear that GitHub has a collaborative review process (the PR) as a first-class concept. Which would need to be retrofitted into Discourse.

PRs welcome

With the above as context, I think we should still go forward with file-based Initiatives tracked on GitHub. As I think it’s an improvement. By we I mean, I’ll champion that and should have the first PRs ready soon.

But in OSS style. No permission is required to work on an alternative if someone has a better idea :smiley: And to be inclusive, I’ll remain open to feedback.

For now though, I have enough input here to work on this change.

2 Likes
15

lol :laughing:

This is something I’m generally positive about between GitHub and Discord as well. Having worked on Discourse mirror revision and poking at the user-api-keys I’ve gotten more familiar with the API as well. But I haven’t got any experience about which sort of integrations would work well. Maybe you can create a topic on what you would suggest there?

Well, very appropriate for this topic is @decentralion’s Review requested: On review culture

My currently open PRs are all ready to go, I need to do more work first :stuck_out_tongue:

16

Just own it. Earlier on the impression I got (from comments and the Cred weights) is that a lot of work was needed in regards to strategy, game design, and community engagement. Now it’s clear that the focus is on developers. That’s totally ok, but just make sure that you own it and communicate that clearly across all words and actions. People don’t mind if you’re transparent, but when projects (esp crypto/tech projects) try to be something they’re not (regardless of their intentions) people generally aren’t into it. If SourceCred is currently only accessible to developers, and you’re trying to recruit developers, I’d also focus on developer/open-source projects as the initial target market. This way you can recruit contributors while you also onboard new end-users. Win/win for all parties involved :slight_smile:

GitHub is an amazing tool, but it suffers from being biased towards developers which limits participation. Also, usually better to find (or create) a tool that fits your workflow vs fitting your workflow to the tools you have. This is a universal truth, but I’ve found that developers trying to stay on GitHub long after they should have graduated to other platforms is a common trend. That being said, if your target market for contributors and users is developers, particularly open source projects, then by all means use GitHub all day long! It’ll be great. Just be aware that if/when you expand to other markets you’ll have to improve UI/UX as well.

This was meant to be a general comment, not anything specific to SourceCred. Sorry if that wasn’t clear lol

Totally. But lots of alphas end up getting used far beyond their originally intended shelf life. It’s a slippery slope. That’s the point I was trying to make here.

Yeah 100%. Just don’t get attached to them or design around them. Tools should work for us, but we should not work for the tools (otherwise we become the tools lol)

I’d focus on developers and GitHub support. Doing one thing for one market and doing it really well will provide a foundation to expand to other markets/use-cases. It’s so easy to lose focus. Don’t lose focus. I’d love to see SourceCred become the absolute best in the world at the thing it does. Deep, then Wide.

LMAO reading through this thread as I comment and it looks like we’re on the same page! Totally agree that OSS is a great initial target market for SourceCred :slight_smile:

100% all the way. This. This. And This some more :slight_smile:

Yeah git is amazing. It’s honestly almost as cool as Bitcoin, but so underappreciated lol

This is blowing my mind right now :boom: In the original thread I was focused on the bus factor thing, but when put simply it’s a really powerful idea: fork Discourse. That would be so great, but then you’d have to figure out how to fork the user’s private data without compromising it, which seems non-trivial. Still, would be so cool to be able to fork and merge Discourse branches.

Yeah GitHub is great for reviewing stuff. Just saying that it’s not great for everything (like broader community engagement). Now, if the target market is developers anyways, then that’s not a problem which is totally ok. Actually solves a lot of problems all at once so that’s great.

17

@burrrata I believe this comment is not appropriate.

You’re making a generalized claim about the whole community, and are presenting it as fact. Even though multiple people in the same thread have already expressed different views.

For me personally, inclusion in the broadest sense of the word is one of the main reasons why I’m excited about and committed to SourceCred. It’s something I spend a lot of time thinking about, advocating, and developing for. It’s the reason I’ve created this topic for feedback, it’s fundamental to open-source, and the workflow I endorse, and is something I’ve brought up explicitly in this thread before. The suggestion to “just own” we’re exclusively targeting developers is something I feel quite offended by.

I’m happy to receive and respond to constructive criticism, but please pay closer attention to what’s already publicly discussed, before making claims, and be respectful of your fellow community members.

2 Likes
18

I think you’re reading into this. There’s no criticism here. I’m just saying that it’s important to be really clear about where the project is at and what it’s goals are. That’s it. The reason there’s a smiley face at the end of the paragraph you quoted is that it’s healthy to know where you’re at, where you’re going, and how you’re going to get there. The more clear and unambiguous you can be about that the better.

Lots and lots of crypto projects try to pretend they’re decentralized or diverse before they really are, and it doesn’t work. Being honest about where you’re at and where you’re going does work. People like that. Right now SourceCred needs more developers and it’s a very developer focused project due to the technical complexity and the stage of development. In the future it might expand to serve more use cases and target markets, but right now it’s very alpha and very dog food. That’s great! Very exciting times :slight_smile:

20

Sigh…

@burrrata, let me first say that I really value your opinions here. The fact that you’re so passionate and knowledgeable about decentralized governance, web3, social issues, etc., and have relevant experience, is rare and valuable. I’m also noticing a disturbing pattern here. Where you write long posts voicing strong opinions, sometimes challenging decisions that have already been made, which then triggers strong emotional responses from other people. These then turn into these long conversations that demand a lot of time, attention and emotional labor from other contributors. We’re a small, bandwidth-limited team. We have been talking about these issues for months now. We’re all generally well aligned in our values, and have agreed that at this stage it is necessary to have @decentralion be a TBD (Temporary Benevolent Dictator) so they can make decisions and move the project forward. You yourself have referenced this post dozens of times. @decentralion has also spent a ton of time gathering feedback and ideas from the community (including yourself), allowed contributors (including yourself) to shape decisions, and has communicated as clearly as possible their vision and future plans (including changing the weights to give developers more cred). It has also been conveyed that this necessarily involves pivoting, which will be emotionally volatile. We don’t have the bandwidth for resolving lots of disputes. To your credit, you are displaying some emotional intelligence in your comments (moreso than most people I work with for sure), but you are a) challenging decisions that have been made, and b) using wording that is going to trigger people, especially in an asynchronous virtual environment (‘it’s a road to ruin’, ‘just own it’, ‘I think you’re reading into this’, etc.). I would actually love to have debates like this in the voice chat. I love that shit. But this posting on Discourse, causing all of this labor for other people, is not working.

I was planning on working on a docs initiative this morning. Instead I’ve spent most of my morning thinking about this and composing this response. Weighting my words so as to not upset people further. But I’m going to be blunt. I don’t have time for this. I’ve spent far too much of my life (I’m probably older than all of you), surrounding myself with intelligent, passionate, creative people (artists, entrepreneurs, etc.) that didn’t. build. anything. Because they sat around fighting over something that only existed in their imaginations, having big philosophical debates. As much as I believe in the potential of SourceCred to address issues in decentralized governance, on-chain UI architecture, deep structural problems in society, etc. (why I’m here!), we’re not going to solve them here arguing instead of building. We’re building a tool for communities can use to address those problems (including ourselves). We’re a small team that now needs to execute. It is widely understood, even by the most decentralized projects, that you have to start out centralized. We’ve already put a ton of time into thinking about this. The theme of the next community call decentralization. That IMO (and other voice channels) is a much more appropriate, productive channel for these conversations.

Last night, I saw that you had posted after being away for a few days. I was hesitant to :heart: it tbh. Not because I don’t like you personally (I do). But because I was acutely aware of recent Discourse drama. But I did it anyway, because I think you have a ton to offer the project. But if I have to spend any more mornings writing posts like this, I’ll be honest, I’ll probably not want to collaborate moving forward.

I don’t think this has to be so dramatic (and hope I’m not just adding fuel to the fire). But I think we’re all value aligned here! I think we have an awesome, inspiring leader that listens more than most. We have a solid plan. Let’s just fucking do this! I realize maybe this may come off as harsh. Maybe I myself need to do some more emotional labor here. But I say this because I want to collaborate more with you @burrrata , not less. Just my 2 satoshis.

4 Likes