Contrib-Checker - Automate Contributor Credit in Research Software

Ensuring Proper Credit in Research Software - Meet Contrib-Checker

In open-source and collaborative coding environments, giving credit where it’s due isn’t just courteous—it’s a matter of transparency, ethics, and even reproducibility. But managing contributor listings manually across metadata files like CITATION.cff or codemeta.json can be tedious or, worse, error-prone.

Enter Contrib-Checker: your automated ally that makes sure contributors in your commit history are properly listed in your project’s credit files.

What Is Contrib-Checker?

Contrib-Checker is a lightweight, MIT-licensed Python tool designed to detect whether the actual git commit contributors are reflected in metadata files such as CITATION.cff or codemeta.json. It supports three usage modes:

• As a Python library
• A command-line utility
• A GitHub Action or GitLab CI integration for automatic enforcement

How It Works

1. Capture Git Authors It runs git log --use-mailmap to gather commit authors, leveraging a .mailmap file if available to unify aliases and emails ([Libraries.io][1]).
2. Cross-Reference Metadata Matches the git authors against the contributor listings in CITATION.cff and codemeta.json.

3. Action

   • Posts comments on PRs or MRs when contributors are missing
   • Optionally fails the workflow if mode: fail is used

When & Why It Matters

• Keep contributor info up to date, especially in fast-moving or collaborative projects
• Automate without friction, especially for pull request workflows
• Ensure project ethics and documentation completeness—important for academic or research-focused software
• Prevent human errors, eliminating the risk of forgetting to update credit files

Quick Example

• github
• gitlab

• Add this snippet to file .github/workflows/contrib-check.yml in your GitHub repository:

  name: Contributor Check
  on:
    pull_request:
      types: [opened, synchronize]
  
  jobs:
    contrib-check:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v3
        - name: Contrib metadata check
          uses: vuillaut/contrib-checker@v1
          with:
            github_token: $
            mode: fail
            ignore_emails: "dependabot[bot]@users.noreply.github.com"
  

  This will run the checks on every pull request. The CI will fail if someone not present in the credit file(s) has added commits to this PR.

• Add this snippet to file .gitlab-ci.yml in your GitLab repository:

  contrib-check:
    stage: test
    image: python:3.11
    script:
      - pip install contrib-checker
      - contrib-checker
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  

Final Thoughts

Contrib-Checker embraces the ethos of modern CI/CD—automation, precision, and transparency—while solving a very human problem: remembering to give credit. From solo academic projects to team-driven open-source libraries, keeping contributors properly acknowledged is made effortless.

Contribute !

Please provide feedback, report bugs or contribute code on https://github.com/vuillaut/contrib-checker