|
| 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 | +This repo comes with a GitHub action configured that will run SourceCred automatically |
| 9 | +every 6 hours, as well as any time you change the configuration. |
| 10 | + |
| 11 | +# About SourceCred Instances |
| 12 | + |
| 13 | +SourceCred is organized around "instances". Every instance must have a |
| 14 | +`sourcecred.json` file at root, which specifies which plugins are active in the |
| 15 | +instance. Config and permanent data (e.g. the Ledger) are stored in the master branch. |
| 16 | +All output or site data gets stored in the `gh-pages` branch by the Github Action. |
| 17 | + |
| 18 | +Configuration files: |
| 19 | +- `config/grain.json` specifies how much Grain to distribute every week. The `maxSimultaneousDistributions` parameter |
| 20 | +determines how many weeks of "back-distributions" to generate if the command hasn't been run in a while (or ever). |
| 21 | +- `config/plugins/$PLUGIN_OWNER/$PLUGIN_NAME` stores plugin-specific data. Each |
| 22 | + plugin has its own directory. See the plugin section below to learn how to configure them. |
| 23 | + |
| 24 | +Permanent Data: |
| 25 | +- `data/ledger.json` keeps a history of all grain distributions and transfers as well as identities added / merged. |
| 26 | + |
| 27 | +Generated Data: |
| 28 | + |
| 29 | +- `cache/` stores intermediate produced by the plugins. This directory should |
| 30 | + not be checked into Git at all. |
| 31 | +- `output/` stores output data generated by SourceCred, including the Cred |
| 32 | + Graph and Cred Scores. This directory should be checked into Git; when |
| 33 | + needed, it may be removed and re-generated by SourceCred. |
| 34 | +- `site/` which stores the compiled SourceCred frontend, which can display data |
| 35 | + stored in the instance. |
| 36 | + |
| 37 | + |
| 38 | +# Setup and Usage |
| 39 | + |
| 40 | +Using this instance as a starting point, you can update the config to include |
| 41 | +just the plugins you want, pointing at the data you care about. We recommend setting up |
| 42 | +your instance locally first and make sure its working before pushing your changes |
| 43 | +to master and using the Github Action. |
| 44 | + |
| 45 | +Get [Yarn] and then run `yarn` to install SourceCred and dependencies. |
| 46 | + |
| 47 | +Update the configuration files according to the plugin guides below. |
| 48 | + |
| 49 | +Then, run the following commands to update the instance: |
| 50 | + |
| 51 | +- `yarn load [...plugins]` loads the cache. By default, it loads all |
| 52 | + plugins, or it can load only specific plugins if requested. |
| 53 | +- `yarn graph [...plugins]` regenerates plugin graphs from the cache; |
| 54 | + these graphs get saved in `output/` |
| 55 | +- `yarn score` computes Cred scores, combining data from all the chosen |
| 56 | + plugins |
| 57 | +- `yarn grain` distributes Grain according to the current Cred scores, and the config in `config/grain.json` |
| 58 | + |
| 59 | +**Generate the frontend:** |
| 60 | + |
| 61 | +- `yarn site` |
| 62 | + |
| 63 | +**Run the frontend:** |
| 64 | + |
| 65 | +- `yarn admin` |
| 66 | + |
| 67 | + |
| 68 | +If you want to clear the cached data, you can do so via: |
| 69 | + |
| 70 | +- `yarn clean` |
| 71 | + |
| 72 | +Running `yarn clean` is a good idea if any plugins fail to load. |
| 73 | + |
| 74 | +If you want to restart from a clean slate and remove all the generated graphs, you can do so via: |
| 75 | + |
| 76 | +- `yarn clean-all` |
| 77 | + |
| 78 | +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. |
| 79 | +**Warning**: If you don't have credentials for every plugin, you might not be able to regenerate parts of the graph. |
| 80 | + |
| 81 | +### Publishing on GitHub pages |
| 82 | + |
| 83 | +Once you've got the instance configured to your satisfaction (see instructions on plugins below), |
| 84 | +commit and push your changes to master (or make a pull request). The Github Action will then generate the frontend |
| 85 | +and deploy it to GitHub Pages. To enable GitHub Pages for your instance, check out [this guide](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). |
| 86 | +Make sure you select `gh-pages` as the branch to publish from. |
| 87 | + |
| 88 | +# Supported Plugins |
| 89 | + |
| 90 | +## GitHub |
| 91 | + |
| 92 | +The GitHub plugin loads GitHub repositories. |
| 93 | + |
| 94 | +You can specify the repositories to load in |
| 95 | +`config/plugins/sourcecred/github/config.json`. |
| 96 | + |
| 97 | +The Github Action automatically has its own GITHUB_TOKEN, but if you need to load data from the |
| 98 | +GitHub plugin locally, you must have a GitHub API key in your environment as |
| 99 | +`$SOURCECRED_GITHUB_TOKEN`. The key should be read-only without any special |
| 100 | +permissions (unless you are loading a private GitHub repository, in which case |
| 101 | +the key needs access to your private repositories). |
| 102 | + |
| 103 | +You can generate a GitHub API key [here](https://github.com/settings/tokens). |
| 104 | + |
| 105 | +## Discourse |
| 106 | + |
| 107 | +The Discourse plugin loads Discourse forums; currently, only one forum can be loaded in any single instance. This does not require any special API |
| 108 | +keys or permissions. You just need to set the server url in `config/plugins/sourcecred/discourse/config.json`. |
| 109 | + |
| 110 | +## Discord |
| 111 | + |
| 112 | +The Discord plugin loads Discord servers, and mints cred on Discord reactions. |
| 113 | + |
| 114 | +To get this setup, you'll first want to enable Developer Mode in your Discord |
| 115 | +client, under User Settings -> Appearance -> Advanced -> Developer Mode. This |
| 116 | +will give you the ability to right-click on items and copy their Discord ids. |
| 117 | + |
| 118 | +Then, right click on the server you want to track, and copy its ID. Modify the |
| 119 | +`config/plugins/sourcecred/discord/config.json` file to have the correct |
| 120 | +guildId. |
| 121 | + |
| 122 | +Next, you'll need to create a Discord application and add it to the server. (This requires admin permissions on that server.) |
| 123 | + |
| 124 | +The first step is to create an application, which you can do here: |
| 125 | +https://discordapp.com/developers/applications |
| 126 | + |
| 127 | +You'll get an application client ID, which you'll need in a future step. |
| 128 | + |
| 129 | +Next, give that application a Bot by clicking on the "Bot" menu option on the left, and then adding a bot. |
| 130 | +The bot will have a token, which you should also save. |
| 131 | + |
| 132 | +Once you've made the bot, you need to invite it to your server. |
| 133 | +You'll need to do so by constructing a URL like: |
| 134 | + |
| 135 | +`https://discordapp.com/api/oauth2/authorize?client_id=${CLIENT_ID}&scope=bot&permissions=8 |
| 136 | + |
| 137 | +Where `${CLIENT_ID}` should be replaced with your application's client id from |
| 138 | +above. For example, if your application's client id is 1234, use the following url: |
| 139 | + |
| 140 | +`https://discordapp.com/api/oauth2/authorize?client_id=1234&scope=bot&permissions=8` |
| 141 | + |
| 142 | +Open that url in a browser where you are logged into Discord, and you'll see a |
| 143 | +menu letting you add the bot to servers you have access to. Add it to the |
| 144 | +server in question, giving it permission to read messages and read message |
| 145 | +history. |
| 146 | + |
| 147 | +You need to add this token into GitHub for the Action to work correctly. |
| 148 | +[Checkout this guide](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets-for-a-repository) |
| 149 | +to see how you can add the token as a Secret that can be read by the Action. Set the name to `SOURCECRED_DISCORD_TOKEN`; |
| 150 | + |
| 151 | +If you are running SourceCred locally, set the bot token to the environment variable `$SOURCECRED_DISCORD_TOKEN`. |
| 152 | + |
| 153 | +You can now load your Discord server. Hooray! |
| 154 | + |
| 155 | +As an added bit of configuration, you can set custom reactionWeights in the |
| 156 | +`reactionWeights` section of the Discord config. These allow you to change how |
| 157 | +much Cred is minted per reaction. |
| 158 | + |
| 159 | +If you want to change the weight for a default reaction, just put the |
| 160 | +reaction's literal emoji in the config.json, as in `"💜": 5` to give the purple |
| 161 | +heart a weight of 5. |
| 162 | + |
| 163 | +If you want to set a custom weight for a custom emoji, you'll need to get the |
| 164 | +custom emoji's server id. You can do this by right-clicking on a custom emoji |
| 165 | +in the server, and clicking "copy link". This will give you a link to the |
| 166 | +emoji's image on Discord's servers, for example: |
| 167 | + |
| 168 | +https://cdn.discordapp.com/emojis/678399364418502669.png?v=1 |
| 169 | + |
| 170 | +The numeric substring is the emoji's ID. You can then specify it in the |
| 171 | +reaction weights file as `$EMOJI_NAME:$EMOJI_ID`, as in: |
| 172 | +`"sourcecred:678399364418502669": 10` to give some server's custom SourceCred |
| 173 | +emoji a weight of 10. |
| 174 | + |
| 175 | +# Removing plugins |
| 176 | + |
| 177 | +To deactivate a plugin, just remove it from the `bundledPlugins` array in the `sourcecred.json` file. |
| 178 | +You can also remove its `config/plugins/OWNER/NAME` directory for good measure. |
| 179 | + |
| 180 | + |
| 181 | + |
| 182 | +[Yarn]: https://classic.yarnpkg.com/ |
| 183 | + |
0 commit comments