SourceCred Example Instance

This repository will contain an example SourceCred instance.

New users of SourceCred are encouraged to fork this repo to start their own instance.

About SourceCred Instances

SourceCred is organized around "instances". Every instance must have a sourcecred.json file at root, which specifies which plugins are active in the instance.

Each instance has the following directory structure:

• config/ stores user-defined configuration.
• config/plugins/$PLUGIN_OWNER/$PLUGIN_NAME stores plugin-specific data. Each plugin has its own directory.
• cache/ stores intermediate produced by the plugins. This directory should not be checked into Git.
• output/ stores output data generated by SourceCred, including the Cred Graph and the Cred Scores. This directory should be checked into Git; when needed, it may be removed and re-generated by SourceCred.
• site/ which stores the compiled SourceCred frontend, which can display data stored in the instance.

The instance is updated via the following commands:

• sourcecred load [...plugins] loads the cache. By default it loads all plugins, or it can load only specific plugins if requested.
• sourcecred graph [...plugins] regenerates plugin graphs from the cache; these graphs are saved in output/
• sourcecred score computes Cred scores, combining data from all the chosen plugins
• sourcecred site re-compiles the SourceCred frontend

Supported Plugins

GitHub

The GitHub plugin loads GitHub repositories.

You can specify the repositories to load in config/plugins/sourcecred/github/config.json. In order to load the GitHub plugin, you must have a GitHub API key in your environment as $SOURCECRED_GITHUB_TOKEN. The key should be read-only without any special permissions (unless you are loading a private GitHub repository, in which case the key needs access to your private repositories).

You can generate a GitHub API key here.

Discourse

The Discourse plugin loads Discourse fourms; currently, only one forum may be loaded in any single instance. This does not require any special API keys or permissions. You just need to set the server url in config/plugins/sourcecred/discourse/config.json.

Discord

The Discord plugin loads Discord servers, and mints cred on Discord reactions.

To get this setup, you'll first want to enable Developer Mode in your Discord client, under User Settings -> Appearance -> Advanced -> Developer Mode. This will give you the ability to right-click on items and copy their Discord ids.

Then, right click on the server you want to track, and copy its ID. Modify the config/plugins/sourcecred/discord/config.json file to have the correct guildId.

Next, you'll need to create a Discord application and add it to the server. (This requires admin permissions on that server.)

The first step is to create an application, which you can do here: https://discordapp.com/developers/applications

You'll get an application client ID, which you'll need in a future step.

Next, give that application a Bot, by click on the "Bot" menu option on the left, and then adding a bot. The bot will have a token, which you should also save.

Once you've made the bot, you need to invite it to your server. You'll need to do so by constructing a url like:

https://discordapp.com/api/oauth2/authorize?client_id=${CLIENT_ID}&scope=bot&permissions=66560

Where ${CLIENT_ID} should be replaced with your application's client id from above. For example, if your application's client id is 1234, use the following url:

https://discordapp.com/api/oauth2/authorize?client_id=1234&scope=bot&permissions=66560

Open that url in a browswer where you are logged into Discord, and you'll see a menu letting you add the bot to servers you have access to. Add it to the server in question, giving it permission to read messages and read message history.

Then, set the bot's token to the environment variable $SOURCECRED_DISCORD_TOKEN.

You can now load your Discord server. Hooray!

As an added bit of configuration, you can set custom reactionWeights in the reactionWeights section of the Discord config. These allow you to change how much Cred is minted per reaction.

If you want to change the weight for a default reaction, just put the reaction's literal emoji in the config.json, as in "💜": 5 to give the purple heart a weight of 5.

If you want to set a custom weight for a custom emoji, you'll need to get the custom emoji's server id. You can do this by right-clicking on a custom emoji in the server, and clicking "copy link". This will give you a link to the emoji's image on Discord's servers, for example:

https://cdn.discordapp.com/emojis/678399364418502669.png?v=1

The numeric substring is the emoji's ID. You can then specify it in the reaction weights file as $EMOJI_NAME:$EMOJI_ID, as in: "sourcecred:678399364418502669": 10 to give some server's custom SourceCred emoji a weight of 10.

Removing plugins

To deactivate a plugin, just remove it from the bundledPlugins array in the sourcecred.json file. You can also remove its config/plugins/OWNER/NAME directory for good measure.

Forking off this instance

Using this instance as a starting point, you can update the config to include just the plugins you want, pointing at the data you care about.

Get Yarn and then run yarn to install SourceCred and dependencies.

Then, run the following commands to update the instance:

• yarn load
• yarn graph
• yarn score

If you want to update the frontend, you can do so via:

• yarn site

Publishing on GitHub pages

Once you've got the instance configured to your satisfaction, you can publish it on GitHub pages by opening the repository settings, scrolling to GitHub pages, and selecting to publish from the master branch.