aboutcode-org / aboutcode-org/scancode-analyzer

Add examples, contributor docs, and developer tooling to improve onboarding and reproducibility

Offen
#67 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
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.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.