Status and Caveats
This plugin is currently in Beta.
Because it's recently been added (April 2020), we're still gaining experience with this plugin in practice. Any current guides and recommendations may change as a result.
One caveat is that an Initiative mixes objective data (who did what) with subjective data (how valuable was that). In SourceCred it's a feature that we can retroactively update those subjective weights. The objective data helps have constructive discussions about, "do we have our facts straight?" and helps to remember what made an Initiative valuable in a future discussion.
Try to avoid shaping the objective data to fit your subjective needs, such as leaving out a contribution because you feel the weight should be lower than some other contributions.
The biggest shortcoming of this plugin currently is around inclusivity.
Creating / updating Initiatives is rather technical, as you need to hand write a JSON file and understand how the plugin works to do so. It also requires a review process because this plugin allows almost arbitrary additions to the Graph, which adds another barrier to being recognized. Validating whether everything has been correctly attributed is also not easy in the current UI, adding another technical barrier.
We're aware of this issue and plan on improving this with more accessible tools. In the meantime if you're using this plugin, it's important to be aware of these barriers and support your community in having access to fair recognition.
All plugins are currently bundled with SourceCred and don't need additional installation. The Initiatives plugin is included as of version 0.5.0 of SourceCred.
This guide assumes you will be tracking Initiatives in a Git repository and this repository can be viewed in a browser. In our case it's pushed to GitHub.
1. Creating an Initiatives directory
We'll want to store our Initiative files in a new directory, tracked in the Git
repository. Let's creatively call this
This directory is where we can store our Initiative files. Note, nesting
directories is currently not supported. So initiative files should be added here
It's important that this directory exists when we're trying to load from it.
So it may be worth adding a
.gitkeep file to this directory as well, so that
this directory exists even when you don't have any Initiative files added yet.
2. Updating project.json
Loading Initiatives currently only works through
project.json config files.
Either create one or upgrade from a previous
project.json version to make
sure it's at version
0.5.0 or greater at the top of the file.
Next, we specify we want to use Initiatives, by adding an
initiatives object in our project file implies that we want to
Note, should there be any errors trying to load the initiatives, it will consider that a fatal error and crash. If you want to disable Initiatives these lines should be removed from the project file.
There's one argument here:
initiatives.remoteUrl: The URL where we can find the canonical Initiatives in a browser. Note we're pointing to the
masterbranch in the example as the canonical is important.
3. Loading a project with Initiatives
To load the updated
project.json which now enables Initiatives, we need to
provide an extra ENV variable.
SOURCECRED_INITIATIVES_DIRECTORY: The local path to our Initiatives directory. This path can be absolute or relative to your current working directory.
Assuming you're running SourceCred in a node environment, your load command might look like this.
If all goes well, you should see initiatives mentioned in the progress output.
You're now ready to add Initiative files to the directory!
- Explain JSON format.
- Explain differences between contribution fields.
- Using URLs vs entries.
- Link back to concepts for details.
- Using the incomplete/complete weights to reduce risk and incentivize.
- Mapping out Initiatives and determining weights.