/github-workflow-examples

GitHub action to generate a sourcecred prototype or graphic for your repository

Primary LanguageShell

Sourcecred Example Workflows

GitHub actions status

This is a repository with example GitHub workflows for generating sourcecred graphics and prototypes. Specifically, we use the sourcecred development and widgets containers to generate either a single graphic, or an entire web interface to show contributions to your repository. You can choose to either generate a contributors graphic, or a prototype.

Generate a Contributor's Graphic

This is what a contributors graphic looks like:

contributors.svg

Essentially, we use sourcecred metrics to create a user profile collage based on the top contributors to your repository, as determined by a SourceCred contribution graph. The git history for this repository is fairly limited, but with more contributors the graphic above would be much more substantial! If you've decided to choose generation of this graphic, you next need to choose a workflow.

1. Choose your workflow

There are currently two derivations of the same workflow:

2. Customize

contributors_pull_request.yml and contributors_automated.yml

  • time: you might want to adjust the cron frequency to be run at a rate that works for you . The pull request example is set to run on a weekly basis, and the automated example runs nightly at 2:30am.
  • filename: the graphic is saved as contributors.svg at the root of the repository, and you can change this if desired.

contributors_pull_request.yml

You might want to customize the workflow in the following ways:

  • script for PR: The script to open the pull request is kept alongside the workflows, and referenced by sha. If you are a developer and need to update the pull_request.sh script, make sure to update the sha as well.
  • branches: currently the pull request is done via a created branch called update/sourcecred-contributors- and then done against master. You can update the Action to adjust these values.
  • auto-delete: If you choose to open new branches, you might want to consider enabling "Auto delete head branches" in your repository settings. This will delete branches after merge.

contributors_automated.yml

  • branch You can customize the branch that is pushed to by changing UPDATE_BRANCH. Currently we push to "contributors-automated" but you might imagine wanting to push an updated graphic to some web interface to display it.

3. Cache

Currently, we cache the "sourcecred_data" folder is the root of the repository that contains previously extracted metadata about contributions. For most cases, this will assist to run the action more quickly, however if you find that a different version of sourcecred/sourcecred:dev is being used (and either outputs an error, or your contribution plot seems off) you can manually invalidate the cache by removing this folder entirely before running the containers:

rm -rf sourcecred_data
mkdir -p sourcecred_data

The updated data will then be saved again to the cache.

4. README

Likely after the first graphic generation, you will want to add a link for it to render in your README.md, as is done here.

![contributors.svg](./contributors.svg)

You can also use the example badge at the top of the README.md to add a badge for your GitHub action. Happy hacking!

Generate a SourceCred Prototype

A more substantial tool is the sourcecred prototype, which includes an interactive graph for your repository. The repository here deploys an example web interface on its GitHub pages.

1. Choose your workflow

There are also two derivations of this same workflow:

2. Customize

prototype_pull_request.yml and prototype_automated.yml

  • time: you might want to adjust the cron frequency to be run at a rate that works for you . The pull request example is set to run on a weekly basis, and the automated example runs nightly at 2:30am.
  • output: Output is default directed to a docs folder, and the idea is that you would deploy this on GitHub pages. You could also change the logic to have static files in the root of the repository, if desired.

prototype_pull_request.yml

You might want to customize the workflow in the following ways:

  • script for PR: The script to open the pull request is kept alongside the workflows, and referenced by sha. If you are a developer and need to update the pull_request.sh script, make sure to update the sha as well.
  • branches: currently the pull request is done via a created branch called update/sourcecred-prototype- and then done against master. You can update the Action to adjust these values.
  • auto-delete: If you choose to open new branches, you might want to consider enabling "Auto delete head branches" in your repository settings. This will delete branches after merge.

prototype_automated.yml

  • branch You can customize the branch that is pushed to by changing UPDATE_BRANCH. Currently we push to "master" but you might imagine wanting to push the entire static content to gh-pages (or somewhere else).

See Examples in the Wild

The following repositories are deploying these pipelines to generate graphics:

Have you used a workflow here and want to add your repository to show? Please open an issue!