@crisog/sourcecred

SourceCred

SourceCred is an open-source tool that enables online communities to create a community-specific contribution score, called Cred, which measures how much value every contributor has added to the project. SourceCred then enables the project to issue tokens, called Grain, to contributors based on their Cred. Grain is purchased by sponsors of the project, and gives sponsors the ability to influence Cred scores.

You can read more at sourcecred.io.

Plugin Architecture

SourceCred is organized around a plugin architecture, which ensures that it can track and reward any kind of contribution, so long as you can assign addresses to contributions, and record how they relate to one another. Currently, we have the following four plugins:

• sourcecred/github: Loads GitHub repositories, including issues, pull requests, and reviews
• sourcecred/discourse: Loads Discourse forums, including posts, topics, and likes
• sourcecred/discord: Loads Discord servers, including messages and reactions
• sourcecred/initiatives: Loads manually added contributions. Still in alpha.

Every plugin has a two-part name in the form $OWNER/$NAME; for example, SourceCred's own GitHub plugin is named sourcecred/github.

The Instance System

SourceCred is organized around the concept of "instances". A SourceCred instance contains all of the configuration and data associataed with Cred and Grain, and optionally may be set up as a deployable website that displays those scores. Each instance has the following directory structure:

./package.json      # SourceCred version and package scripts
./sourcecred.json   # Lists enabled plugins
./config            # User-edited config files
./data              # Persistent data, e.g. ledger history
./output            # Output data, may be removed/regenerated
./site              # Bundled frontend, if included
./cache             # Temporary data, should not be checked in to git

We recommend storing instances in a Git repository. The best way to set up an instance is by forking [sourcecred/example-instance].

Once your instance is setup, you can update it with the following commands:

• yarn load: Regenerate the cache
• yarn graph: Recompute graphs from cache
• yarn score: Re-run Cred calculations
• yarn site: Regenerate the website (potentially upgrading it)
• yarn go: Runs load, graph and score in sequence.

If you want to update the data for just one plugin (e.g. sourcecred/github), you can use the following command sequence:

• yarn load sourcecred/github
• yarn graph sourcecred/github
• yarn score

Contributing Guidelines

If you'd like to contribute to the codebase, we ask you to follow the following steps:

1. Drop by our Discord.

Come to the #intros channel and introduce yourself. Let us know that you're interested in helping out. We're friendly and will be happy to help you get oriented.

2. Read our Contributing Guidelines.

We pride ourself on tidy software engineering; part of how we do that is by splitting our changes up into many small, atomic commits, each of which are easy to review. If you'd like to work alongside us, we ask you to adopt our practices.

3. Find an issue to work on.

You can check out the issues marked contributions welcome, or ask in the Discord's #programming channel if anyone has something you can contribute to.

Getting Support

If you need help with SourceCred, try asking for help in the #tech-support channel on our Discord. You can also come to our weekly dev meeting, on Mondays at 12pm PT. (Check out the SourceCred calendar.)

Development Setup

Dependencies

• Install Node (tested on v14.x.x, v12.x.x and v10.x.x).
• Install Yarn (tested on v1.7.0-v1.22.10).
• For macOS users: Ensure that your environment provides GNU coreutils. See this comment for details about what, how, and why.

If you want to work on the GitHub plugin, you should create a GitHub API token. No special permissions are required.

Then, set it in your environment:

export SOURCECRED_GITHUB_TOKEN=1234....asdf

If you want to work on the Discord plugin, you need a Discord bot token specific to the bot/server that you are loading. See instructions here.

Building SourceCred Locally

First, run the following commands to clone and build SourceCred:

git clone https://github.com/sourcecred/sourcecred.git
cd sourcecred
yarn
yarn build

Using A Modified Backend

You'll likely want to test out your modified version of SourceCred on an instance you're familiar with. A convenient way to do that is to create an alias for your altered version of SourceCred. Here's an example of how to do so in a bash shell:

SC_REPOSITORY_DIR=`pwd`
alias scdev='node "$SC_REPOSITORY_DIR"/bin/sourcecred.js'
cd $MY_SC_INSTANCE
# Run the `sourcecred go` command, in your instance, using your modified code.
scdev go

While making backend changes, you may find it useful to view a diff between the last generated graph and a newly generated graph by running scdev graph -d and/or running a no-write simulation by running scdev graph -s The graph.json is stored in the instance, so you can easily compare results across backend branches.

Using a Modified Frontend

If you've made changes to the SourceCred frontend, you can preview and test it using our builtin development server:

yarn start

By default, the server will run in the tiny example instance located at ./sharness/__snapshots__/example-instance. If you'd like to run it in your instance instead, start it via: yarn start --instance $PATH_TO_INSTANCE.

License

SourceCred is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)

Acknowledgements

We’d like to thank Protocol Labs for funding and support of SourceCred.