Skip to content

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

@saitejareddy05

Description

@saitejareddy05

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions