├── .env.example ├── .github ├── dependabot.yml └── workflows │ ├── distribute-grain.yml │ └── generate-instance.yml ├── .gitignore ├── README.md ├── config ├── currencyDetails.json ├── dependencies.json ├── grain.json ├── personalAttributions.json └── plugins │ └── sourcecred │ ├── discord │ └── config.json │ ├── discourse │ └── config.json │ └── github │ └── config.json ├── data ├── ledger.json └── updater.txt ├── package.json ├── sourcecred.json └── yarn.lock /.env.example: -------------------------------------------------------------------------------- 1 | SOURCECRED_DISCORD_TOKEN=TjkyOTk1OFg1NTA2MTQ4NgVw.TqpnSA.fWIrGvOaQuT8Z-5-8dN-hdChkub 2 | SOURCECRED_GITHUB_TOKEN=913043df20670ec28e4428eacc80218a1bcce0dd 3 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # Please see the documentation for all configuration options: 2 | # https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 3 | 4 | version: 2 5 | updates: 6 | - package-ecosystem: "npm" # See documentation for possible values 7 | directory: "/" # Location of package manifests 8 | schedule: 9 | interval: "daily" 10 | 11 | - package-ecosystem: "github-actions" 12 | directory: "/" 13 | schedule: 14 | interval: "daily" 15 | -------------------------------------------------------------------------------- /.github/workflows/distribute-grain.yml: -------------------------------------------------------------------------------- 1 | name: Distribute Grain 2 | on: 3 | # A new Cred interval every Sunday. We'll distribute Grain 5 minutes 4 | # after the new interval 5 | schedule: 6 | - cron: 5 0 * * 0 # 00:05 UTC, 16:05 PST 7 | push: 8 | branches: 9 | # allows us to test this workflow, or manually generate distributions 10 | # PRSs created from grain-trigger-* branches are targeted 11 | # on their immediate base branches, as opposed to master 12 | - "grain-trigger-*" 13 | 14 | jobs: 15 | distribute-grain: 16 | runs-on: ubuntu-latest 17 | env: 18 | NODE_OPTIONS: --max_old_space_size=8192 19 | steps: 20 | - uses: actions/checkout@v2.3.4 21 | 22 | - name: Install Packages 🔧 23 | run: | 24 | yarn --frozen-lockfile 25 | 26 | - name: Load Data and Compute Cred 🧮 27 | run: yarn sourcecred go 28 | env: 29 | SOURCECRED_GITHUB_TOKEN: ${{ secrets.SOURCECRED_GITHUB_TOKEN }} 30 | SOURCECRED_DISCORD_TOKEN: ${{ secrets.SOURCECRED_DISCORD_TOKEN }} 31 | 32 | - name: Distribute Grain 💸 33 | run: yarn grain > grain_output.txt 34 | 35 | - name: Set environment variables 36 | id: pr_details 37 | run: | 38 | echo "PULL_REQUEST_TITLE=Scheduled grain distribution for week ending $(date +"%B %dth, %Y")" >> $GITHUB_ENV 39 | description="This PR was auto-generated on $(date +%d-%m-%Y) \ 40 | to add the latest grain distribution to our instance. 41 | 42 | $(cat grain_output.txt)" 43 | description="${description//'%'/'%25'}" 44 | description="${description//$'\n'/'%0A'}" 45 | description="${description//$'\r'/'%0D'}" 46 | echo "::set-output name=pr_body::$description" 47 | rm grain_output.txt 48 | 49 | # To create a pull request, use this block: 50 | - name: Create commit and PR for ledger changes 51 | id: pr 52 | uses: peter-evans/create-pull-request@v3.10.0 53 | with: 54 | branch: generated-ledger 55 | branch-suffix: timestamp 56 | committer: credbot 57 | # author appears to be overridden when the default github action 58 | # token is used for checkout 59 | author: credbot 60 | commit-message: update calculated ledger 61 | title: ${{ env.PULL_REQUEST_TITLE }} 62 | body: ${{ steps.pr_details.outputs.pr_body }} 63 | 64 | # To commit directly to the main branch, comment the above PR step, and uncomment these steps: 65 | # - name: Commit ledger changes 66 | # run: | 67 | # git config user.name 'credbot' 68 | # git config user.email 'credbot@users.noreply.github.com' 69 | # git add data/ledger.json 70 | # git add config 71 | # git commit --allow-empty -m '${{ env.COMMIT_TITLE }}' -m '${{ steps.details.outputs.commit_body }}' 72 | # - name: Push Ledger 73 | # run: git push 74 | -------------------------------------------------------------------------------- /.github/workflows/generate-instance.yml: -------------------------------------------------------------------------------- 1 | name: Generate Cred Instance 2 | on: 3 | # Trigger on merging to main. 4 | push: 5 | branches: 6 | - main 7 | # As well as every 24 hours (at 0:00 UTC). 8 | schedule: 9 | - cron: 0 0 * * * 10 | 11 | jobs: 12 | GenerateCredInstance: 13 | runs-on: ubuntu-latest 14 | env: 15 | NODE_OPTIONS: --max_old_space_size=8192 16 | steps: 17 | - uses: actions/checkout@v2.3.4 18 | with: 19 | persist-credentials: false # Required to make github pages deployment work correctly 20 | 21 | - name: Cache Data # Cache SourceCred Data, invalidating if any of the config changes or the SC version is updated 22 | uses: actions/cache@v2.1.6 23 | with: 24 | path: '**/cache' 25 | key: SC-${{ runner.os }}-${{ hashFiles('**/config.json', '**/sourcecred.json', '**/yarn.lock') }} 26 | 27 | - name: Install Packages 🔧 28 | run: yarn --frozen-lockfile 29 | 30 | - name: Load Data and Compute Cred 🧮 31 | run: | 32 | yarn sourcecred go 33 | yarn sourcecred analysis 34 | env: 35 | SOURCECRED_GITHUB_TOKEN: ${{ secrets.SOURCECRED_GITHUB_TOKEN }} 36 | SOURCECRED_DISCORD_TOKEN: ${{ secrets.SOURCECRED_DISCORD_TOKEN }} 37 | 38 | - name: Generate Frontend 🏗 39 | run: | 40 | yarn sourcecred site 41 | rm -rf ./site/{output,data,config,sourcecred.json} 42 | cp -r ./{output,data,config,sourcecred.json,package.json,yarn.lock} ./site/ 43 | 44 | - name: Deploy 🚀 45 | uses: JamesIves/github-pages-deploy-action@4.1.4 46 | with: 47 | token: ${{ secrets.GITHUB_TOKEN }} 48 | branch: gh-pages 49 | folder: site 50 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | site/ 3 | output/ 4 | cache/ 5 | 6 | .env 7 | **/.DS_Store 8 | **/.DS_Store? 9 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 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 use this template repo to start their own 6 | instance. 7 | 8 | This repo comes with a GitHub action configured that will run SourceCred automatically 9 | every 24 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 main branch. 16 | All output or site data gets stored in the `gh-pages` branch by the Github Action. 17 | 18 | Configuration files: 19 | 20 | - `config` has JSON files that will be hand-edited to configure your instance (more on this below). 21 | 22 | Permanent Data: 23 | 24 | - `data/ledger.json` keeps a history of all grain distributions and transfers as well as identities added / merged. This should not be hand-edited. 25 | 26 | Generated Data: 27 | 28 | - `cache/` stores intermediate produced by the plugins. This directory should 29 | not be checked into Git at all. 30 | - `output/` stores output data generated by SourceCred, including the Cred 31 | Graph and Cred Scores. This directory should be checked into Git; when 32 | needed, it may be removed and re-generated by SourceCred. 33 | - `site/` which stores the compiled SourceCred frontend, which can display data 34 | stored in the instance. 35 | 36 | # Setup and Usage 37 | 38 | Using this instance as a starting point, you can update the config to include 39 | the plugins you want, pointing at the data you care about. We recommend setting up 40 | your instance locally first and make sure it's working before pushing your changes 41 | to main and using the Github Action. 42 | 43 | **Setting up a SourceCred Instance requires basic knowledge of:** 44 | 45 | - using a terminal 46 | - using git 47 | - hand-editing JSON files 48 | 49 | ## Step 1: Do Initial Setup 50 | 51 | 1. Hit the big green "Use this template" button on github. (do not fork) 52 | 53 | 1. Use a **git** client to clone your new repo locally. 54 | 55 | 1. Get [Yarn], navigate to the cloned repo directory in a terminal, and then run `yarn` to install SourceCred and dependencies. 56 | 57 | 1. Enable the plugins you want to use by adding them to the `bundledPlugins` array in the `sourcecred.json` file. To disable a plugin, simply remove it. For example, 58 | to enable all the plugins: 59 | 60 | ```json 61 | { 62 | "bundledPlugins": [ 63 | "sourcecred/discourse", 64 | "sourcecred/discord", 65 | "sourcecred/github" 66 | ] 67 | } 68 | ``` 69 | 70 | 5. If you are using the GitHub or Discord plugin, copy the `.env.example` file to a `.env` file: 71 | 72 | ```shell script 73 | cp .env.example .env 74 | ``` 75 | 76 | ## Step 2: Configure Plugins 77 | 78 | ### GitHub 79 | 80 | The GitHub plugin loads GitHub repositories. 81 | 82 | You can specify the repositories to load in 83 | `config/plugins/sourcecred/github/config.json`. 84 | 85 | In order for SourceCred to access your GitHub repos, 86 | you must have a GitHub API key in your `.env` file as 87 | `SOURCECRED_GITHUB_TOKEN=` (copy the `.env.example` file for reference). The key should be read-only without any special 88 | scopes or permissions (unless you are loading a private GitHub repository, in which case 89 | the key needs access to your private repositories). 90 | 91 | You can generate a GitHub API key [here](https://github.com/settings/tokens). 92 | 93 | ### Discourse 94 | 95 | The Discourse plugin loads Discourse forums; currently, only one forum can be loaded in any single instance. This does not require any special API 96 | keys or permissions. You just need to set the server url in `config/plugins/sourcecred/discourse/config.json`. The discourse forum must be publicly accessible via the URL that is set, however. The forum must be accessible without a login. 97 | 98 | ### Discord 99 | 100 | The Discord plugin loads Discord servers, and mints Cred on Discord reactions. In order for SourceCred to 101 | access your Discord server, you need to generate a "bot token" and paste it in the `.env` file as 102 | `SOURCECRED_DISCORD_TOKEN=` (copy the `.env.example` file for reference). 103 | 104 | The full instructions for setting up the Discord plugin can be found in the [Discord plugin page](https://sourcecred.io/docs/beta/plugins/discord/#configuration) 105 | in the SourceCred documentation. 106 | 107 | ## Step 3: Configure CredRank Weights 108 | 109 | Our current core algorithm, CredRank, is a variation of an algorithm called PageRank. This is a graph-based algorithm that requires weights to be set for the nodes and edges. We provide default weights, and if you want, you can skip this section for now. When you're ready to decide for yourself how Cred should flow through the graph, follow these instructions: 110 | 111 | 1. Run `yarn sourcecred serve`, open `localhost:6006` in a browser, and navigate to the Weight Configuration page. 112 | 1. Set the node and edge weights for each plugin. See [this guide](https://sourcecred.io/docs/beta/cred#choosing-weights) and the [plugin docs](https://sourcecred.io/docs/beta/plugins/github/) for help. 113 | 1. Click "Download weights", move the downloaded file from your downloads folder to the `config/` folder in your instance, and then make sure the name is exactly `weights.json` 114 | 115 | ## Step 3 (alternative): Configure our experimental algorithm CredEquate 116 | 117 | For a comparison of the two available algorithms, and example configs, see: https://sourcecred.io/docs/guides/core-algorithm/ 118 | 119 | ## Step 4: Configure Dependency Cred 120 | 121 | In `config/dependencies.json` you'll notice there is a default configuration for recognizing SourceCred as a dependency that powers your community. This will create bonus Cred and give it to an identity named `sourcecred`, which will be activated to receive rewards. By default it is set to 0.05 (5% of minted Cred). 122 | 123 | If you choose to keep or increase our dependency cred, rewards distributed to our community support the longevity and development of the project. If you are interested in possibly getting extra tech support or feature prioritization for higher dependency cred, reach out on [Discord](https://sourcecred.io/discord) in our _#any-questions_ channel! If you want to lower or remove the dependency cred, we're dedicated to open source and you totally can. 124 | 125 | NOTE: WE ARE NO LONGER ACCEPTING REWARDS/DONATIONS AT THIS TIME 126 | 127 | ## Step 5: Test with the CLI 128 | 129 | Use the following commands to run your instance locally: 130 | 131 | **Load Data** 132 | 133 | - `yarn load` loads the data from each plugin into the cache. Run this anytime you want to re-load the data from 134 | your plugins. 135 | 136 | **Run SourceCred** 137 | 138 | - `yarn start` creates the cred graph, computes cred scores and runs the front end interface which you can access at `localhost:6006` 139 | in your browser. 140 | 141 | NOTE: this command will not load any new data from Discord / GitHub / Discourse, etc. If you want to re-load 142 | all the latest user activity, run `yarn load` again. 143 | 144 | **Troubleshooting** 145 | 146 | - `yarn clean` will clear any cached data that was loaded by the plugins. You can run this if any plugins fail to load. Run `yarn load` and `yarn start` after this to refresh the data. 147 | 148 | - `yarn clean-all` gives you an even cleaner state. Run it if the `yarn start` command fails due to a change in the config or breaking changes in a new version of SourceCred, and then run `yarn load` and `yarn start` to refresh. 149 | 150 | If you continue to run into errors, check our [Tech Support FAQ](https://sourcecred.io/docs/setup/FAQ). If you don't see your error there, or you need more help, hop into our [Discord](https://sourcecred.io/discord) and ask in the #tech-support channel. 151 | 152 | ## Step 6: Set Up GitHub Actions 153 | 154 | 1. Once you get `yarn start` working, push your local changes to GitHub. 155 | 1. _(Skip this if you are not using the Discord or GitHub plugins.)_ In GitHub, go to your repository's Settings tab and click Secrets in the left sidebar. Add the API tokens from your local .env file by clicking _New repository secret_ and adding `SOURCECRED__TOKEN` as the name and the token as the value. 156 | 1. Go to the repository's Actions tab. If the most recent Generate Cred Instance workflow has failed, click into it and click "Re-run all jobs". Wait or come back to verify that Generate Cred Instance succeeds. 157 | 158 | ## Step 7: Publish with GitHub Pages 159 | 160 | The Generate Cred Instance workflow has deployed a static site to a branch called `gh-pages`. 161 | 162 | 1. Go to Settings > Pages 163 | 1. Select the gh-pages branch if it is not already selected. 164 | 1. Click "Select theme" and then click the green "Select Theme" to choose a random theme. This is required but it does not matter what theme is chosen. 165 | 1. Verify that the URL it gives you works. 166 | 167 | ## Step 8: Distribute Rewards 168 | 169 | By default, rewards are called Grain by SourceCred. If you would like to re-skin the rewards to represent your community's token, edit `config/currencyDetails.json` 170 | 171 | The command `yarn grain` distributes Grain according to the current Cred scores, and the config in `config/grain.json`. This repo contains a GitHub Action for automatically distributing Grain. It will run every Sunday and create a Pull Request 172 | with the ledger updated with the new grain balances based on the users Cred scores. 173 | 174 | 1. Configure the amounts to distribution and the distribution strategy by editing "config/grain.json". There are three different policies that can be used to control 175 | how the grain gets distributed: "IMMEDIATE", "BALANCED", and "RECENT". For info on what each policy does, how to choose the right policy for your community, and how Grain operates in general, see [How Grain Works](https://sourcecred.io/docs/beta/grain). 176 | 1. **The grain distribution will not take effect until you manually approve and merge it every week in the Pull Requests tab of your instance repository. You should do this weekly, or you will encounter merge conflicts.** If you want to skip the Pull Request step and commit directly to the main branch, read the instructions in `.github/workflows/distribute-grain.yml` and make the described edit. 177 | 178 | **Example Grain Configuration** 179 | 180 | Below is an example `grain.json` file for a configuration that uses a combination of all three policies. Here we tell SourceCred to distribute 1,000 grain every week, with 25% (250 grain) distributed according to `IMMEDIATE`, 25% (250 grain) distributed according to `BALANCED`, and 50% (500 grain) distributed according to `RECENT`. `MaxSimultaneousDistributions` can be used to back-fill multiple weeks of missing distributions, but can usually just be kept at 1. 181 | 182 | ```json 183 | { 184 | "maxSimultaneousDistributions": 1, 185 | "allocationPolicies": [ 186 | { 187 | "budget": "250", 188 | "numIntervalsLookback": 1, 189 | "policyType": "IMMEDIATE" 190 | }, 191 | { 192 | "budget": "450", 193 | "discount": 0.5, 194 | "policyType": "RECENT" 195 | }, 196 | { 197 | "budget": "250", 198 | "numIntervalsLookback": 0, 199 | "policyType": "BALANCED" 200 | } 201 | ] 202 | } 203 | ``` 204 | 205 | ### Optionally use our CSV Grain Integration 206 | 207 | Instead of doing Grain balance accounting in SourceCred, you can instead make Grain distributions output CSV files to directly send payouts to participants using Disperse.app or Gnosis Safe CSV app. To try this out, see: https://sourcecred.io/docs/guides/csv-grain/ 208 | 209 | ## That's it! 210 | 211 | You've set up a SourceCred instance! We'd love to know you're out there. _**Introduce yourself and link your repository**_ on our [Discord](https://sourcecred.io/discord) or @ us on [Twitter](https://twitter.com/sourcecred). 212 | 213 | # Beyond the basics 214 | 215 | If you want to go deeper, you can access lower-level commands in the SourceCred CLI in the form of: `yarn sourcecred `. 216 | For a list of what's available, and what each command does, run `yarn sourcecred help`. Then run `yarn sourcecred help ` to see what feature flags are available for each command. 217 | 218 | [yarn]: https://classic.yarnpkg.com/ 219 | -------------------------------------------------------------------------------- /config/currencyDetails.json: -------------------------------------------------------------------------------- 1 | { 2 | "currencyName": "Grain", 3 | "currencySuffix": " g" 4 | } 5 | -------------------------------------------------------------------------------- /config/dependencies.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "name": "SourceCred", 4 | "periods": [], 5 | "autoActivateOnIdentityCreation": true, 6 | "autoInjectStartingPeriodWeight": 0.05 7 | } 8 | ] 9 | -------------------------------------------------------------------------------- /config/grain.json: -------------------------------------------------------------------------------- 1 | { 2 | "allocationPolicies": [ 3 | ], 4 | "maxSimultaneousDistributions": 1 5 | } -------------------------------------------------------------------------------- /config/personalAttributions.json: -------------------------------------------------------------------------------- 1 | [ 2 | ] 3 | -------------------------------------------------------------------------------- /config/plugins/sourcecred/discord/config.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "channelWeightConfig": { 4 | "defaultWeight": 1, 5 | "weights": { 6 | } 7 | }, 8 | "guildId": "678348980639498428", 9 | "includeNsfwChannels": false, 10 | "propsChannels": [ 11 | ], 12 | "reactionWeightConfig": { 13 | "applyAveraging": false, 14 | "defaultWeight": 1, 15 | "weights": { 16 | "sourcecred:678399364418502669": 10, 17 | "👍": 1 18 | } 19 | }, 20 | "roleWeightConfig": { 21 | "defaultWeight": 1, 22 | "weights": { 23 | } 24 | } 25 | } 26 | ] -------------------------------------------------------------------------------- /config/plugins/sourcecred/discourse/config.json: -------------------------------------------------------------------------------- 1 | {"serverUrl": "https://sourcecred-test.discourse.group"} 2 | -------------------------------------------------------------------------------- /config/plugins/sourcecred/github/config.json: -------------------------------------------------------------------------------- 1 | {"repositories": ["sourcecred-test/example-github"]} 2 | -------------------------------------------------------------------------------- /data/ledger.json: -------------------------------------------------------------------------------- 1 | [] 2 | -------------------------------------------------------------------------------- /data/updater.txt: -------------------------------------------------------------------------------- 1 | Auto-generated. Commit changes, do not edit, do not delete. 2 | 0.10.0 -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "template-instance", 3 | "version": "0.1.0", 4 | "description": "A template repo for creating a SourceCred instance", 5 | "repository": "git@github.com:sourcecred/template-instance.git", 6 | "author": "SourceCred Team ", 7 | "license": "MIT", 8 | "private": true, 9 | "dependencies": { 10 | "sourcecred": "^0.11.2" 11 | }, 12 | "scripts": { 13 | "clean": "rimraf cache site", 14 | "clean-all": "yarn clean && rimraf output", 15 | "load": "dotenv sourcecred load", 16 | "start": "dotenv -- sourcecred go --no-load && sourcecred serve", 17 | "grain": "sourcecred grain" 18 | }, 19 | "devDependencies": { 20 | "rimraf": "^3.0.2", 21 | "dotenv-cli": "^4.0.0" 22 | } 23 | } 24 | -------------------------------------------------------------------------------- /sourcecred.json: -------------------------------------------------------------------------------- 1 | { 2 | "bundledPlugins": [] 3 | } 4 | --------------------------------------------------------------------------------