aboutcode-org / aboutcode-org/scancode-analyzer

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

Aberta
#67 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
4
Forks
4
Métricas de merge de PRs
Nenhum PR com merge em 30d

Descrição

# 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.

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.