Skip to content

Commit 94f9b92

Browse files
vuillautvuillaut
authored
Merge pull request #2 from vuillaut/package
complete refactoring to make a python package
2 parents 812dca2 + f10b9a1 commit 94f9b92

20 files changed

+2606
-435
lines changed

‎.github/workflows/pytest.yml‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,24 +11,33 @@ jobs:
1111
runs-on: ubuntu-latest
1212
strategy:
1313
matrix:
14-
python-version: ['3.11', '3.12', '3.13']
14+
python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
1515

1616
steps:
1717
- name: Checkout
1818
uses: actions/checkout@v5
19+
with:
20+
fetch-depth: 0 # Need full history for git tests
1921

2022
- name: Setup Python
2123
uses: actions/setup-python@v5
2224
with:
2325
python-version: ${{ matrix.python-version }}
2426

25-
- name: Install dependencies
27+
- name: Install package and dependencies
2628
run: |
2729
python -m pip install --upgrade pip
28-
pip install -r requirements.txt
29-
pip install pytest
30+
pip install -e .
31+
pip install pytest pytest-cov
32+
33+
- name: Run unit tests
34+
run: |
35+
pytest tests/ -v --cov=contrib_checker --cov-report=xml --cov-report=term
3036
31-
- name: Run tests
32-
run: pytest -q
33-
env:
34-
PYTHONPATH: ${{ github.workspace }}
37+
- name: Upload coverage to Codecov
38+
if: matrix.python-version == '3.11'
39+
uses: codecov/codecov-action@v3
40+
with:
41+
file: ./coverage.xml
42+
flags: unittests
43+
name: codecov-umbrella

‎MANIFEST.in‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
include README.md
2+
include LICENSE
3+
include CITATION.cff
4+
include CONTRIBUTING.md
5+
include requirements.txt
6+
include action.yml
7+
include .gitlab-ci.yml
8+
include GITLAB_CI_USAGE.md
9+
include contrib_checker_core.py
10+
include check_contributors_github.py
11+
include check_contributors_gitlab.py
12+
recursive-include tests *.py
13+
global-exclude __pycache__
14+
global-exclude *.py[co]

‎README.md‎

Lines changed: 164 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,110 @@
1-
# ContribChecker
1+
# contrib-checker
22

3-
ContribChecker is a GitHub Action and helper script that verifies that contributors who appear in the git history are listed in the repository metadata files (`CITATION.cff` and `codemeta.json`). It uses a `.mailmap` file to unify multiple emails/names for the same person.
3+
contrib-checker is a library and set of tools that verify contributors from git history are properly listed in repository metadata files (`CITATION.cff` and `codemeta.json`).
4+
It provides:
45

5-
Why this is useful
6-
- Keeps citation and credit metadata accurate when new contributors add commits
7-
- Helps projects maintain reproducible credit and citation information
6+
- **Python library**: Installable package for programmatic use
7+
- **Command-line tool**: `contrib-checker` CLI for local checking
8+
- **GitHub Action**: Automated checking in GitHub workflows
9+
- **GitLab CI**: Support for GitLab merge request checking
810

9-
What this repository provides
10-
- A Python script at `check_contributors.py` that performs the check
11-
- A GitHub Actions bot at `action.yml` that runs the script on PR events
11+
## Installation
1212

13-
How it works
14-
- The action runs on PR events. It runs `git log --use-mailmap --format='%aN <%aE>' BASE..HEAD` to collect commit authors, so ensure `.mailmap` is present if you need to unify multiple emails.
15-
- It compares commit authors against `CITATION.cff` and `codemeta.json` and posts a comment if missing contributors are found.
16-
- If `mode: fail` is set in the config, the Action will fail the job (exit code 1).
13+
### As a Python package
1714

15+
```bash
16+
pip install contrib-checker
17+
```
18+
19+
### For development
20+
21+
```bash
22+
git clone https://github.com/vuillaut/contrib-checker.git
23+
cd contrib-checker
24+
pip install -e .
25+
26+
```
27+
28+
## Usage
29+
30+
### Command-line tool
31+
32+
After installation, you can use the `contrib-checker` command:
33+
34+
```bash
35+
# Check all contributors in current repository
36+
contrib-checker
37+
38+
# Check with specific mode
39+
contrib-checker --mode fail
40+
41+
# Check with ignore lists
42+
contrib-checker --ignore-emails [email protected] --ignore-logins bot-user
43+
44+
# Check specific commit range
45+
contrib-checker --from-sha abc123 --to-sha def456
46+
47+
# Use specific repository path
48+
contrib-checker --repo-path /path/to/repo
49+
50+
# See all options
51+
contrib-checker --help
52+
```
53+
54+
### As a Python library
55+
56+
```python
57+
from contrib_checker import ContributorChecker
58+
from pathlib import Path
59+
60+
# Initialize checker
61+
config = {
62+
'mode': 'warn', # or 'fail'
63+
'ignore_emails': ['[email protected]'],
64+
'ignore_logins': ['bot-user']
65+
}
66+
67+
checker = ContributorChecker(
68+
repo_path=Path('.'),
69+
config=config
70+
)
71+
72+
# Check all contributors
73+
success, results = checker.check_all_contributors()
74+
75+
# Check specific commit range
76+
success, results = checker.check_range_contributors(
77+
from_sha='abc123',
78+
to_sha='def456',
79+
description='PR commits'
80+
)
81+
82+
# Check results
83+
if results['missing_overall']:
84+
print("Missing contributors:")
85+
for contributor in results['missing_overall']:
86+
print(f" {contributor}")
87+
```
88+
89+
### Platform-specific usage
90+
91+
```python
92+
# GitHub-specific wrapper
93+
from contrib_checker import GitHubContributorChecker
1894

19-
## Quick start
95+
github_checker = GitHubContributorChecker()
96+
success = github_checker.check_pr_contributors()
97+
98+
# GitLab-specific wrapper
99+
from contrib_checker import GitLabContributorChecker
100+
101+
gitlab_checker = GitLabContributorChecker()
102+
success = gitlab_checker.check_mr_contributors()
103+
```
104+
105+
## GitHub Action Setup
106+
107+
### Quick start
20108

21109
1. Ensure your repository has `CITATION.cff` and/or `codemeta.json` with author/contributor entries.
22110
2. Add a `.mailmap` at the repository root if you need to unify alternate emails or names from the git history.
@@ -26,6 +114,16 @@ How it works
26114
### Example `.github/workflows/contrib-check.yml`
27115

28116
```yaml
117+
name: Contributor Check
118+
119+
on:
120+
pull_request:
121+
types: [opened, synchronize]
122+
123+
permissions:
124+
contents: read
125+
pull-requests: write # allows posting comments on PRs
126+
29127
jobs:
30128
contrib-check:
31129
runs-on: ubuntu-latest
@@ -36,12 +134,60 @@ jobs:
36134
with:
37135
github_token: ${{ secrets.GITHUB_TOKEN }}
38136
mode: warn # or 'fail' to make the workflow fail when contributors are missing
39-
ignore_emails: "dependabot[bot]@users.noreply.github.com,[email protected],[email protected]"
40-
ignore_logins: "dependabot[bot],github-actions[bot],ci-bot"
137+
ignore_emails: "dependabot[bot]@users.noreply.github.com,[email protected]"
138+
ignore_logins: "dependabot[bot],github-actions[bot]"
41139
```
42140
141+
## GitLab CI Setup
142+
143+
See [GITLAB_CI_USAGE.md](GITLAB_CI_USAGE.md) for detailed GitLab CI setup instructions.
144+
145+
### Example `.gitlab-ci.yml`
146+
147+
```yaml
148+
contrib-check:
149+
stage: test
150+
image: python:3.11
151+
script:
152+
- pip install contrib-checker
153+
- contrib-checker
154+
rules:
155+
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
156+
```
157+
158+
## How it works
159+
160+
- Uses `git log --use-mailmap` to collect commit authors, so ensure `.mailmap` is present if you need to unify multiple emails
161+
- Compares commit authors against `CITATION.cff` and `codemeta.json` contributors
162+
- Posts comments on GitHub PRs or GitLab MRs when missing contributors are found
163+
- Can be configured to fail CI when contributors are missing (`mode: fail`)
164+
43165
## Requirements
44166

45-
- GitHub Actions must be enabled for your repository.
46-
- A `CITATION.cff` or `codemeta.json` file must be present and properly formatted.
47-
- Optional: A `.mailmap` file if you need to unify contributor names/emails from git history.
167+
- Python 3.8+
168+
- Git repository with contributor metadata files
169+
- For GitHub Actions: `CITATION.cff` or `codemeta.json` file
170+
- For GitLab CI: Same metadata files plus GitLab API token
171+
- Optional: `.mailmap` file to unify contributor names/emails
172+
173+
## Configuration
174+
175+
The tool can be configured via:
176+
177+
1. **Configuration file**: `.github/contrib-metadata-check.yml` (GitHub) or environment variables (GitLab)
178+
2. **Command-line arguments**: When using the CLI
179+
3. **Environment variables**: For CI/CD integration
180+
181+
### Configuration options
182+
183+
- `mode`: `warn` (default) or `fail`
184+
- `ignore_emails`: List of email addresses to ignore
185+
- `ignore_logins`: List of login names to ignore
186+
187+
## Contributing
188+
189+
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
190+
191+
## License
192+
193+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

‎action.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,12 @@ runs:
3030
with:
3131
python-version: '3.x'
3232

33-
- name: Install deps
34-
run: python -m pip install -r ${{ github.action_path }}/requirements.txt
33+
- name: Install contrib-checker package
34+
run: python -m pip install ${{ github.action_path }}
3535
shell: bash
3636

37-
- name: Run check script
38-
run: python ${{ github.action_path }}/check_contributors.py
37+
- name: Run contributor check
38+
run: python -m contrib_checker.github
3939
shell: bash
4040
env:
4141
GITHUB_TOKEN: ${{ inputs.github_token }}

0 commit comments

Comments
 (0)