b85f5330ee
* WIP: cli admin command
* configure admin command to load ledger admin view
an express service was implemented, which serves the default site from
the instances
test plan: run `sourcecred admin` and browse to the ledger admin
instance to ensure it loads
* implement GET and POST handlers for ledger.json
The GET localhost:6006/data/ledger.json request will return
the ledger.json file if it exists
The POST request will write the submitted json to disk at
./data/ledger.json
test plan: run `$ sourcecred admin` or `$ yarn admin` then
post some json to the path by doing something like
```
$ curl --header "Content-Type: application/json" \
--request POST \
--data '{"username":"derp","password":"slerp"}' \
http://localhost:6006/data/ledger.json
```
and ensure there are no errors.
then
```
$ curl http://localhost:6006/data/ledger.json
```
and ensure the submitted json is returned
* remove unused variables
* Add Ledger to the UI load result
Note: This will fail if there is no ledger file. An empty JSON array is
technically a valid ledger, so if you want to update the example
instance just use:
`echo [] > data/ledger.json`
Test plan: Not yet tested, integrate into frontend
* implement button to save ledger to disk
test-plan: put and empty array ("[]") in the instance's ledger.json
file, then start the admin service "yarn admin" or "sourcecred admin"
then generate some ledger data using the identity interface and ensure
it saves back to disk
* Load ledger from disk for real
* add text middleware to express libdefs
* move ledger disk saving from application/json to text/plain
ledger.json files are encoded in such a way that they are indented and
escaped for some readability from the CLI. using json content-typing
will discard that escaping. By treating the payload as raw text, that
encoding is preserved
test-plan: modify and save a canonically serialized ledger.json file
from the browser frontend and observe that the spacing is preserved in
the file saved to disk
* remove unused deps and improve server console prompt
test-plan: start the admin server and ensure the frontend can create and
modify identities, then save the ledger.json file to disk successfully
* comments and capitalization
test-plan: `yarn flow` should still pass after this change
* remove redundant static middleware
we don't need to configure a static service for a subdirectory of a
statically-served directory
test-plan: ensure ledger.json can still be fetched either via curl or
the web frontend when the admin service is running
* remove address from fetch post request
if we're fetching to/from the parent address that served the javascript
we're calling from, an address is unnecessary
test-plan: make sure updated ledger.json files still POST back to disk
* add instance check
attempt to load the instance configurtion. If the config cannot be
loaded, an error will be throw indicating that the sourcecred.json file
cannot be found
test-plan: run `sourcecred admin` outside of an instance directory and
ensure it fails while looking for sourcecred.json
run `sourcecred admin` in an instance directory and ensure the service
starts up
Co-authored-by: Dandelion Mané <decentralion@dandelion.io>
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,graphandscorein 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/githubyarn graph sourcecred/githubyarn 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.
Development Setup
Dependencies
- Install Node (tested on v12.x.x and v10.x.x).
- Install Yarn (tested on v1.7.0).
- 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:
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
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.