|
1 | | -# template-instance |
2 | | -A template repo for running a SourceCred instance |
| 1 | +# SourceCred Template Instance |
| 2 | + |
| 3 | +This repository contains a template for running a SourceCred instance. |
| 4 | + |
| 5 | +New users of SourceCred are encouraged to fork this repo to start their own |
| 6 | +instance. |
| 7 | + |
| 8 | +# About SourceCred Instances |
| 9 | + |
| 10 | +SourceCred is organized around "instances". Every instance must have a |
| 11 | +`sourcecred.json` file at root, which specifies which plugins are active in the |
| 12 | +instance. |
| 13 | + |
| 14 | +Each instance has the following directory structure: |
| 15 | +- `config/` stores user-defined configuration. |
| 16 | +- `config/plugins/$PLUGIN_OWNER/$PLUGIN_NAME` stores plugin-specific data. Each |
| 17 | + plugin has its own directory. |
| 18 | +- `cache/` stores intermediate produced by the plugins. This directory should |
| 19 | + not be checked into Git. |
| 20 | +- `output/` stores output data generated by SourceCred, including the Cred |
| 21 | + Graph and the Cred Scores. This directory should be checked into Git; when |
| 22 | + needed, it may be removed and re-generated by SourceCred. |
| 23 | +- `site/` which stores the compiled SourceCred frontend, which can display data |
| 24 | + stored in the instance. |
| 25 | + |
| 26 | +The instance is updated via the following commands: |
| 27 | +- `sourcecred load [...plugins]` loads the cache. By default it loads all |
| 28 | + plugins, or it can load only specific plugins if requested. |
| 29 | +- `sourcecred graph [...plugins]` regenerates plugin graphs from the cache; |
| 30 | + these graphs are saved in `output/` |
| 31 | +- `sourcecred score` computes Cred scores, combining data from all the chosen |
| 32 | + plugins |
| 33 | +- `sourcecred site` re-compiles the SourceCred frontend |
| 34 | + |
| 35 | +# Supported Plugins |
| 36 | + |
| 37 | +## GitHub |
| 38 | + |
| 39 | +The GitHub plugin loads GitHub repositories. |
| 40 | + |
| 41 | +You can specify the repositories to load in |
| 42 | +`config/plugins/sourcecred/github/config.json`. In order to load the GitHub |
| 43 | +plugin, you must have a GitHub API key in your environment as |
| 44 | +`$SOURCECRED_GITHUB_TOKEN`. The key should be read-only without any special |
| 45 | +permissions (unless you are loading a private GitHub repository, in which case |
| 46 | +the key needs access to your private repositories). |
| 47 | + |
| 48 | +You can generate a GitHub API key [here](https://github.com/settings/tokens). |
| 49 | + |
| 50 | +## Discourse |
| 51 | + |
| 52 | +The Discourse plugin loads Discourse fourms; currently, only one forum may be loaded in any single instance. This does not require any special API |
| 53 | +keys or permissions. You just need to set the server url in `config/plugins/sourcecred/discourse/config.json`. |
| 54 | + |
| 55 | +## Discord |
| 56 | + |
| 57 | +The Discord plugin loads Discord servers, and mints cred on Discord reactions. |
| 58 | + |
| 59 | +To get this setup, you'll first want to enable Developer Mode in your Discord |
| 60 | +client, under User Settings -> Appearance -> Advanced -> Developer Mode. This |
| 61 | +will give you the ability to right-click on items and copy their Discord ids. |
| 62 | + |
| 63 | +Then, right click on the server you want to track, and copy its ID. Modify the |
| 64 | +`config/plugins/sourcecred/discord/config.json` file to have the correct |
| 65 | +guildId. |
| 66 | + |
| 67 | +Next, you'll need to create a Discord application and add it to the server. (This requires admin permissions on that server.) |
| 68 | + |
| 69 | +The first step is to create an application, which you can do here: |
| 70 | +https://discordapp.com/developers/applications |
| 71 | + |
| 72 | +You'll get an application client ID, which you'll need in a future step. |
| 73 | + |
| 74 | +Next, give that application a Bot, by click on the "Bot" menu option on the left, and then adding a bot. |
| 75 | +The bot will have a token, which you should also save. |
| 76 | + |
| 77 | +Once you've made the bot, you need to invite it to your server. |
| 78 | +You'll need to do so by constructing a url like: |
| 79 | + |
| 80 | +`https://discordapp.com/api/oauth2/authorize?client_id=${CLIENT_ID}&scope=bot&permissions=66560` |
| 81 | + |
| 82 | +Where `${CLIENT_ID}` should be replaced with your application's client id from |
| 83 | +above. For example, if your application's client id is 1234, use the following url: |
| 84 | + |
| 85 | +`https://discordapp.com/api/oauth2/authorize?client_id=1234&scope=bot&permissions=66560` |
| 86 | + |
| 87 | +Open that url in a browswer where you are logged into Discord, and you'll see a |
| 88 | +menu letting you add the bot to servers you have access to. Add it to the |
| 89 | +server in question, giving it permission to read messages and read message |
| 90 | +history. |
| 91 | + |
| 92 | +Then, set the bot's token to the environment variable `$SOURCECRED_DISCORD_TOKEN`. |
| 93 | + |
| 94 | +You can now load your Discord server. Hooray! |
| 95 | + |
| 96 | +As an added bit of configuration, you can set custom reactionWeights in the |
| 97 | +`reactionWeights` section of the Discord config. These allow you to change how |
| 98 | +much Cred is minted per reaction. |
| 99 | + |
| 100 | +If you want to change the weight for a default reaction, just put the |
| 101 | +reaction's literal emoji in the config.json, as in `"💜": 5` to give the purple |
| 102 | +heart a weight of 5. |
| 103 | + |
| 104 | +If you want to set a custom weight for a custom emoji, you'll need to get the |
| 105 | +custom emoji's server id. You can do this by right-clicking on a custom emoji |
| 106 | +in the server, and clicking "copy link". This will give you a link to the |
| 107 | +emoji's image on Discord's servers, for example: |
| 108 | + |
| 109 | +https://cdn.discordapp.com/emojis/678399364418502669.png?v=1 |
| 110 | + |
| 111 | +The numeric substring is the emoji's ID. You can then specify it in the |
| 112 | +reaction weights file as `$EMOJI_NAME:$EMOJI_ID`, as in: |
| 113 | +`"sourcecred:678399364418502669": 10` to give some server's custom SourceCred |
| 114 | +emoji a weight of 10. |
| 115 | + |
| 116 | +# Removing plugins |
| 117 | + |
| 118 | +To deactivate a plugin, just remove it from the `bundledPlugins` array in the `sourcecred.json` file. |
| 119 | +You can also remove its `config/plugins/OWNER/NAME` directory for good measure. |
| 120 | + |
| 121 | +# Forking off this instance |
| 122 | + |
| 123 | +Using this instance as a starting point, you can update the config to include |
| 124 | +just the plugins you want, pointing at the data you care about. |
| 125 | + |
| 126 | +Get [Yarn] and then run `yarn` to install SourceCred and dependencies. |
| 127 | + |
| 128 | +Then, run the following commands to update the instance: |
| 129 | + |
| 130 | +- `yarn load` |
| 131 | +- `yarn graph` |
| 132 | +- `yarn score` |
| 133 | + |
| 134 | +If you want to update the frontend, you can do so via: |
| 135 | + |
| 136 | +- `yarn site` |
| 137 | + |
| 138 | +If you want to clear the cached data, you can do so via: |
| 139 | + |
| 140 | +- `yarn clean` |
| 141 | + |
| 142 | +Running `yarn clean` is a good idea if any plugins fail to load. |
| 143 | + |
| 144 | +If you want to restart from a clean slate and remove all the generated graphs, you can do so via: |
| 145 | + |
| 146 | +- `yarn clean-all` |
| 147 | + |
| 148 | +Run `yarn clean-all` if the `yarn graph` command fails due to a change in the config or breaking changes in a new version of SourceCred. |
| 149 | +**Warning**: If you don't have credentials for every plugin, you might not be able to regenerate parts of the graph. |
| 150 | + |
| 151 | +[Yarn]: https://classic.yarnpkg.com/ |
| 152 | + |
| 153 | +# Publishing on GitHub pages |
| 154 | + |
| 155 | +Once you've got the instance configured to your satisfaction, you can publish |
| 156 | +it on GitHub pages by opening the repository settings, scrolling to GitHub |
| 157 | +pages, and selecting to publish from the master branch. |
| 158 | + |
0 commit comments