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 to 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 an additional 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 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!