@crisog/sourcecred
v0.7.18
Published
a tool for communities to measure and reward value creation
Downloads
14
Readme
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 reviewssourcecred/discourse
: Loads Discourse forums, including posts, topics, and likessourcecred/discord
: Loads Discord servers, including messages and reactionssourcecred/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 cacheyarn graph
: Recompute graphs from cacheyarn score
: Re-run Cred calculationsyarn site
: Regenerate the website (potentially upgrading it)yarn go
: Runsload
,graph
andscore
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.