SourceCred

SourceCred Instance System

SourceCred Instance System

Initiative Description:

Currently, managing SourceCred instances is messy and ad-hoc. For an example, you can look at the very hacky update script which runs SourceCred’s own cred. Because we don’t have good support for initializing, updating, and publishing SourceCred instances, it’s hard for anyone else to adopt SourceCred (and it’s also a pain for me to manage).

I propose that we build a first-class instance system for SourceCred. It would have the following properties:

  • Fully configuration-based; a package.json file or config.yml type file will contain information that configures every plugin, the overall instance, the weights and parameters, etc. See @Beanow’s post with more details.

  • Fully self-contained and reproducible; a cred instance contains all the information needed to interpret and reproduce the cred in the instance. For example, the cred graph and the scores will be present as accessible data in the instance. Also, running a http server in the root of the instance will launch the cred explorer, enabling interactive exploration of the cred

Benefits:

Having this system will massively simplify usage of SourceCred, and ensure that cred is always reproducible. This will be a convenience win for us, and also make adopting SourceCred enormously easier.

Implementation plan:

  • Define a configuration spec for the interface
    • Estimate 2 hours
  • Add an export-frontend command to the CLI that can export a working frontend
    • Estimate 4 hours
  • Re-write SourceCred frontend and build so that it assumes 1 project per instance, not multiple projects
    • Estimate 4 hours
  • Rewrite sourcecred command so that it loads the config spec and then exports scores, graph, and frontend
    • Estimate 4 hours
  • Write documentation for the instance system
    • Estimate 2 hours

Estimated Work (hours):

16

Dependencies:

None

References

Links to contributions:

None yet

About export-frontend. I’ve been wondering for a bit if the explorer shouldn’t be a pre-compiled module you can embed. Or host separately. Only pointing to data.

As currently every “instance” includes a lot of extra stuff too. Like https://sfosc.org/sourcecred/ The into page here, which is largely superseded by to the updated https://sourcecred.io/ homepage. I think most instances will link only to the project list or directly to an explorer instance.

Currently we’re also using server-side rendering to have URLs for these. However I think many more parameters are interesting to create URLs for. Like narrowing down to a timeframe, or linking to the github repositories view. Something like using GET parameters or hash parameters make sense to use instead. What that would also allow is to be completely driven by static files in the data folder. e.g. no need to use webpack to generate folders and minimal HTML files just so you can have your URLs the way you’d like. Which would eliminate the need for end-users to even compile the frontend.

1 Like

Yep, that sounds great to me. I think maybe we should scope out a sub-initiative which does the precursor work:

  • Remove the ability for a SourceCred instance to map to multiple projects (which requires the build step to compile the routes in)
  • Remove the old intro page (which is superseded by sourcecred.io)
  • Pre-compile the frontend and commit it (?)

I’m not exactly sure what the right intermediate state there is between where we are now and having the instnace system, but it feels like doing these 3 steps would be a good start.

Cross referencing earlier discussion: https://github.com/sourcecred/sourcecred/issues/1272

@Beanow, you should be able to add it directly to the references list on the initiative (it’s setup as a wiki post)

Good point. Didn’t realize that was what you were going for with the References section till filling out the template once.