aboutcode-org / aboutcode-org/scancode-analyzer
Add examples, contributor docs, and developer tooling to improve onboarding and reproducibility
- Vorherrschende Sprache
- Python
- Sterne
- 4
- Forks
- 4
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Beschreibung
# Add examples, contributor docs, and developer tooling to improve onboarding and reproducibility
**Summary**
The repository lacks a small set of developer‑ and user‑facing artifacts that make it hard for new users and contributors to run, test, and extend the analyzer. Add a minimal, high‑impact set of files that enable an end‑to‑end example run, contributor guidance, and basic developer tooling.
**Why this matters**
- New users cannot quickly try the analyzer without a runnable example and clear CLI usage.
- Contributors lack onboarding and standards, increasing friction for PRs.
- Reproducibility and CI confidence are reduced without an example, pre‑commit hooks, and coverage reporting.
**Proposed changes (files to add)**
1. **`examples/sample-scancode.json`**
- A tiny, valid ScanCode JSON containing one or two file entries and minimal metadata for a quick demo run.
2. **`examples/run-example.sh`** (and optional `examples/run-example.bat`)
- Script that creates a venv, installs the package in editable mode, runs the analyzer on `sample-scancode.json`, and writes `examples/output.json`.
3. **`CONTRIBUTING.md`**
- How to set up dev env, run tests, run the example, branch/PR conventions, commit message style, and review expectations.
4. **`CODE_OF_CONDUCT.md`**
- Standard Contributor Covenant or equivalent.
5. **`.pre-commit-config.yaml`** and **`requirements-dev.txt`**
- Pre-commit hooks for `black`, `isort`, `flake8`; dev dependencies pinned for reproducible dev installs.
6. **`Dockerfile`** (minimal)
- Container image to run the analyzer with pinned runtime deps and an example `docker run` command in README.
7. **CI additions**
- Add a CI job to run the example and publish coverage reports (coverage badge to README).
8. **README quickstart snippet**
- Short instructions showing how to run the example and run tests locally.
**Acceptance criteria**
- `examples/run-example.sh` runs successfully on a clean machine and produces `examples/output.json` when executed following README quickstart steps.
- `CONTRIBUTING.md` documents how to run tests and the example, and how to submit a PR.
- `.pre-commit-config.yaml` is functional and documented in `CONTRIBUTING.md`.
- `Dockerfile` builds and runs the analyzer against `examples/sample-scancode.json`.
- CI runs include a job that executes the example and a coverage job that uploads a coverage artifact or posts a badge.
**Implementation notes and suggestions**
- Keep `sample-scancode.json` minimal and clearly labeled as synthetic test data.
- Make `run-example.sh` idempotent and safe to run multiple times. Use `python -m venv .venv` and `pip install -e .[dev]`.
- Use a small base image for the `Dockerfile` (e.g., `python:3.11-slim`) and copy only required files to keep image size small.
- Add a short `docs/usage.rst` or README section that documents the CLI entry point and example flags used by the script.
- For CI, add a matrix for the primary supported Python version and a single job that runs the example to ensure the example remains valid.
**Suggested labels**
- `enhancement`
- `good first issue`
- `documentation`
- `devops`
**Can you assign to me @saitejareddy05**
**My PR checklist for submission**
- [ ] Add `examples/sample-scancode.json` and `examples/run-example.sh`.
- [ ] Add `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.
- [ ] Add `.pre-commit-config.yaml` and `requirements-dev.txt`.
- [ ] Add `Dockerfile` and README quickstart snippet.
- [ ] Add CI job to run example and coverage.
- [ ] Update `README.rst` with a one‑paragraph quickstart and link to `CONTRIBUTING.md`.
- [ ] Run `pre-commit` hooks and ensure tests pass locally.
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Bewertung
Dieses Issue wurde noch nicht bewertet.