# contrib-checker
contrib-checker checks if code contributors are properly listed in metadata files such as `CITATION.cff` and `codemeta.json` based on the git history.
It provides:
- **Python library**: Installable package for programmatic use
- **Command-line tool**: `contrib-checker` CLI for local checking
- **GitHub Action**: Automated checking in GitHub workflows
- **GitLab CI**: Support for GitLab merge request checking
## Installation
### As a Python package
```bash
pip install contrib-checker
```
### For development
```bash
git clone https://github.com/vuillaut/contrib-checker.git
cd contrib-checker
pip install -e .
```
## Usage
### Command-line tool
After installation, you can use the `contrib-checker` command:
```bash
# Check all contributors in current repository
contrib-checker
# Check with specific mode
contrib-checker --mode fail
# Check with ignore lists
contrib-checker --ignore-emails bot@example.com --ignore-logins bot-user
# Check specific commit range
contrib-checker --from-sha abc123 --to-sha def456
# Use specific repository path
contrib-checker --repo-path /path/to/repo
# See all options
contrib-checker --help
```
### As a Python library
```python
from contrib_checker import ContributorChecker
from pathlib import Path
# Initialize checker
config = {
'mode': 'warn', # or 'fail'
'ignore_emails': ['bot@example.com'],
'ignore_logins': ['bot-user']
}
checker = ContributorChecker(
repo_path=Path('.'),
config=config
)
# Check all contributors
success, results = checker.check_all_contributors()
# Check specific commit range
success, results = checker.check_range_contributors(
from_sha='abc123',
to_sha='def456',
description='PR commits'
)
# Check results
if results['missing_overall']:
print("Missing contributors:")
for contributor in results['missing_overall']:
print(f" {contributor}")
```
### Platform-specific usage
```python
# GitHub-specific wrapper
from contrib_checker import GitHubContributorChecker
github_checker = GitHubContributorChecker()
success = github_checker.check_pr_contributors()
# GitLab-specific wrapper
from contrib_checker import GitLabContributorChecker
gitlab_checker = GitLabContributorChecker()
success = gitlab_checker.check_mr_contributors()
```
## GitHub Action Setup
### Quick start
1. Ensure your repository has `CITATION.cff` and/or `codemeta.json` with author/contributor entries.
2. Add a `.mailmap` at the repository root if you need to unify alternate emails or names from the git history.
3. Add this action (or copy the workflow) into your repo in `.github/workflows/contrib-check.yml`; the included workflow triggers on pull requests.
### Example `.github/workflows/contrib-check.yml`
```yaml
name: Contributor Check
on:
pull_request:
types: [opened, synchronize]
permissions:
contents: read
pull-requests: write # allows posting comments on PRs
jobs:
contrib-check:
runs-on: ubuntu-latest
steps:
- name: Contrib metadata check
uses: vuillaut/contrib-checker@main
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
mode: warn # or 'fail' to make the workflow fail when contributors are missing
ignore_emails: "dependabot[bot]@users.noreply.github.com,ci-bot@example.com"
ignore_logins: "dependabot[bot],github-actions[bot]"
```
## GitLab CI Setup
See [GITLAB_CI_USAGE.md](GITLAB_CI_USAGE.md) for detailed GitLab CI setup instructions.
### Example `.gitlab-ci.yml`
```yaml
contrib-check:
stage: test
image: python:3.11
script:
- pip install contrib-checker
- contrib-checker
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
```
## How it works
- Uses `git log --use-mailmap` to collect commit authors, so ensure `.mailmap` is present if you need to unify multiple emails
- Compares commit authors against `CITATION.cff` and `codemeta.json` contributors
- Posts comments on GitHub PRs or GitLab MRs when missing contributors are found
- Can be configured to fail CI when contributors are missing (`mode: fail`)
## Requirements
- Python 3.8+
- Git repository with contributor metadata files
- For GitHub Actions: `CITATION.cff` or `codemeta.json` file
- For GitLab CI: Same metadata files plus GitLab API token
- Optional: `.mailmap` file to unify contributor names/emails
## Configuration
The tool can be configured via:
1. **Configuration file**: `.github/contrib-metadata-check.yml` (GitHub) or environment variables (GitLab)
2. **Command-line arguments**: When using the CLI
3. **Environment variables**: For CI/CD integration
### Configuration options
- `mode`: `warn` (default) or `fail`
- `ignore_emails`: List of email addresses to ignore
- `ignore_logins`: List of login names to ignore
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "contrib-checker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git, contributors, citation, metadata, github-actions, gitlab-ci",
"author": null,
"author_email": "Thomas Vuillaume <thomas.vuillaume@lapp.in2p3.fr>",
"download_url": "https://files.pythonhosted.org/packages/85/6b/9a08ef6348896dd821d01c72790dfcf2abe3e20663f42f24c78f832e40f4/contrib_checker-1.0.0.tar.gz",
"platform": null,
"description": "# contrib-checker\n\ncontrib-checker checks if code contributors are properly listed in metadata files such as `CITATION.cff` and `codemeta.json` based on the git history.\n\nIt provides:\n\n- **Python library**: Installable package for programmatic use\n- **Command-line tool**: `contrib-checker` CLI for local checking\n- **GitHub Action**: Automated checking in GitHub workflows \n- **GitLab CI**: Support for GitLab merge request checking\n\n## Installation\n\n### As a Python package\n\n```bash\npip install contrib-checker\n```\n\n### For development\n\n```bash\ngit clone https://github.com/vuillaut/contrib-checker.git\ncd contrib-checker\npip install -e .\n\n```\n\n## Usage\n\n### Command-line tool\n\nAfter installation, you can use the `contrib-checker` command:\n\n```bash\n# Check all contributors in current repository\ncontrib-checker\n\n# Check with specific mode\ncontrib-checker --mode fail\n\n# Check with ignore lists\ncontrib-checker --ignore-emails bot@example.com --ignore-logins bot-user\n\n# Check specific commit range\ncontrib-checker --from-sha abc123 --to-sha def456\n\n# Use specific repository path\ncontrib-checker --repo-path /path/to/repo\n\n# See all options\ncontrib-checker --help\n```\n\n### As a Python library\n\n```python\nfrom contrib_checker import ContributorChecker\nfrom pathlib import Path\n\n# Initialize checker\nconfig = {\n 'mode': 'warn', # or 'fail'\n 'ignore_emails': ['bot@example.com'],\n 'ignore_logins': ['bot-user']\n}\n\nchecker = ContributorChecker(\n repo_path=Path('.'),\n config=config\n)\n\n# Check all contributors\nsuccess, results = checker.check_all_contributors()\n\n# Check specific commit range\nsuccess, results = checker.check_range_contributors(\n from_sha='abc123',\n to_sha='def456', \n description='PR commits'\n)\n\n# Check results\nif results['missing_overall']:\n print(\"Missing contributors:\")\n for contributor in results['missing_overall']:\n print(f\" {contributor}\")\n```\n\n### Platform-specific usage\n\n```python\n# GitHub-specific wrapper\nfrom contrib_checker import GitHubContributorChecker\n\ngithub_checker = GitHubContributorChecker()\nsuccess = github_checker.check_pr_contributors()\n\n# GitLab-specific wrapper \nfrom contrib_checker import GitLabContributorChecker\n\ngitlab_checker = GitLabContributorChecker()\nsuccess = gitlab_checker.check_mr_contributors()\n```\n\n## GitHub Action Setup\n\n### Quick start\n\n1. Ensure your repository has `CITATION.cff` and/or `codemeta.json` with author/contributor entries.\n2. Add a `.mailmap` at the repository root if you need to unify alternate emails or names from the git history.\n3. Add this action (or copy the workflow) into your repo in `.github/workflows/contrib-check.yml`; the included workflow triggers on pull requests.\n\n\n### Example `.github/workflows/contrib-check.yml`\n\n```yaml\nname: Contributor Check\n\non:\n pull_request:\n types: [opened, synchronize]\n\npermissions:\n contents: read\n pull-requests: write # allows posting comments on PRs\n\njobs:\n contrib-check:\n runs-on: ubuntu-latest\n \n steps:\n - name: Contrib metadata check\n uses: vuillaut/contrib-checker@main\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n mode: warn # or 'fail' to make the workflow fail when contributors are missing\n ignore_emails: \"dependabot[bot]@users.noreply.github.com,ci-bot@example.com\"\n ignore_logins: \"dependabot[bot],github-actions[bot]\"\n```\n\n## GitLab CI Setup\n\nSee [GITLAB_CI_USAGE.md](GITLAB_CI_USAGE.md) for detailed GitLab CI setup instructions.\n\n### Example `.gitlab-ci.yml`\n\n```yaml\ncontrib-check:\n stage: test\n image: python:3.11\n script:\n - pip install contrib-checker\n - contrib-checker\n rules:\n - if: $CI_PIPELINE_SOURCE == \"merge_request_event\"\n```\n\n## How it works\n\n- Uses `git log --use-mailmap` to collect commit authors, so ensure `.mailmap` is present if you need to unify multiple emails\n- Compares commit authors against `CITATION.cff` and `codemeta.json` contributors\n- Posts comments on GitHub PRs or GitLab MRs when missing contributors are found\n- Can be configured to fail CI when contributors are missing (`mode: fail`)\n\n## Requirements\n\n- Python 3.8+\n- Git repository with contributor metadata files\n- For GitHub Actions: `CITATION.cff` or `codemeta.json` file\n- For GitLab CI: Same metadata files plus GitLab API token\n- Optional: `.mailmap` file to unify contributor names/emails\n\n## Configuration\n\nThe tool can be configured via:\n\n1. **Configuration file**: `.github/contrib-metadata-check.yml` (GitHub) or environment variables (GitLab)\n2. **Command-line arguments**: When using the CLI\n3. **Environment variables**: For CI/CD integration\n\n### Configuration options\n\n- `mode`: `warn` (default) or `fail`\n- `ignore_emails`: List of email addresses to ignore\n- `ignore_logins`: List of login names to ignore\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Check if code contributors are properly listed in metadata files such as CITATION.cff and codemeta.json based on the git history",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/vuillaut/contrib-checker",
"Issues": "https://github.com/vuillaut/contrib-checker/issues",
"Repository": "https://github.com/vuillaut/contrib-checker"
},
"split_keywords": [
"git",
" contributors",
" citation",
" metadata",
" github-actions",
" gitlab-ci"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "70b8019de04d1ea1396fc2b1488f789fbbcea5bd12681d0785d0577540789a6a",
"md5": "2975ffdbc2a13cb343f3a956140c32b8",
"sha256": "502a61b7905b120f9dbd0f2b98f04bb282f80f05e5da2b15c1016c980d0f48b9"
},
"downloads": -1,
"filename": "contrib_checker-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2975ffdbc2a13cb343f3a956140c32b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13613,
"upload_time": "2025-08-19T09:25:39",
"upload_time_iso_8601": "2025-08-19T09:25:39.570033Z",
"url": "https://files.pythonhosted.org/packages/70/b8/019de04d1ea1396fc2b1488f789fbbcea5bd12681d0785d0577540789a6a/contrib_checker-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "856b9a08ef6348896dd821d01c72790dfcf2abe3e20663f42f24c78f832e40f4",
"md5": "3f09215e34cffe58ddaf0ad809dc5564",
"sha256": "fad000903a6334b41b81401395017c30604ec777636731982a831745108c2b5a"
},
"downloads": -1,
"filename": "contrib_checker-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3f09215e34cffe58ddaf0ad809dc5564",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23077,
"upload_time": "2025-08-19T09:25:40",
"upload_time_iso_8601": "2025-08-19T09:25:40.955232Z",
"url": "https://files.pythonhosted.org/packages/85/6b/9a08ef6348896dd821d01c72790dfcf2abe3e20663f42f24c78f832e40f4/contrib_checker-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 09:25:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vuillaut",
"github_project": "contrib-checker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "PyYAML",
"specs": []
},
{
"name": "requests",
"specs": []
}
],
"lcname": "contrib-checker"
}
JSON
