From 227e2f21d6ed4bd129978795fb2d5c847991af87 Mon Sep 17 00:00:00 2001 From: Prajwal7-2002 Date: Tue, 27 Oct 2026 18:06:50 +0530 Subject: [PATCH] chore(governance): add PR template, issue forms, security policy, code of conduct, and hardened CI --- .github/ISSUE_TEMPLATE/bug_report.yml | 65 ++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 44 +++++++++++++++ .github/pull_request_template.md | 28 ++++++++++ .github/workflows/ci.yml | 3 + .pre-commit-config.yaml | 18 ++++++ CODE_OF_CONDUCT.md | 43 ++++++++++++++ SECURITY.md | 31 +++++++++++ uv.lock | 2 +- 9 files changed, 241 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .pre-commit-config.yaml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..7da7cd8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,65 @@ +name: "๐Ÿ› Bug Report" +description: "Report a bug, numerical error, or bit-packing discrepancy in quantbench-engine" +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thank you for reporting an issue in `quantbench-engine`! Please ensure you are running the latest version. + + - type: textarea + id: description + attributes: + label: Description of the Bug + description: What went wrong during quantization, packing, or model conversion? + placeholder: "When quantizing a linear layer with INT4 and group_size=32..." + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Minimal Steps to Reproduce + description: Exact CLI command or minimal Python code snippet reproducing the numerical or execution issue. + placeholder: | + import torch + from quantbench.quant.packing import pack_int4, unpack_int4 + # ... + validations: + required: true + + - type: textarea + id: traceback + attributes: + label: Error Traceback / Logs + description: Paste the console traceback inside a code block. + render: shell + validations: + required: false + + - type: textarea + id: environment + attributes: + label: Environment Diagnostics + description: Details about your environment. + placeholder: | + - OS: Windows 11 / Ubuntu 22.04 / macOS + - Python Version: (e.g. 3.12.10) + - PyTorch Version: (e.g. 2.5.1) + - Device: (CUDA / CPU / MPS) + - quantbench-engine Version: (e.g. 0.1.2) + validations: + required: true + + - type: checkboxes + id: confirmation + attributes: + label: Validation Checklist + options: + - label: I have verified this bug occurs on the latest `main` branch or PyPI release. + required: true + - label: I have checked open/closed issues to avoid duplicates. + required: true + - label: I am willing to submit a Pull Request to fix this. + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..d73aece --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: ๐Ÿ“– Quantbench Documentation & Educational Guides + url: https://github.com/Prajwal7-2002/quantbench#readme + about: Read our comprehensive guides on sub-byte quantization and hardware sparsity. + - name: ๐Ÿ”’ Report a Security Vulnerability + url: https://github.com/Prajwal7-2002/quantbench/security/advisories/new + about: Privately disclose sensitive security vulnerabilities to maintainers. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..56fc635 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,44 @@ +name: "โœจ Feature Request / Quantization Scheme Proposal" +description: "Suggest a new sub-byte quantization scheme, calibration algorithm, or hardware backend" +title: "[Feature]: " +labels: ["enhancement", "proposal"] +body: + - type: markdown + attributes: + value: | + Thank you for proposing a feature for `quantbench-engine`! We welcome proposals for sub-byte quantization algorithms, calibration methods, and packing runtimes. + + - type: textarea + id: problem + attributes: + label: Motivation / Use Case + description: What quantization scheme, calibration method, or compression format does this address? + placeholder: "We want to support FP4 (NV-FP4 microscaling) with E2M1 representation..." + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed Implementation & Bit-Packing Layout + description: Describe the mathematical formulation, bit-layout, and vectorized PyTorch implementation. + placeholder: | + Implement `pack_fp4` using 2 weights per byte with a per-block 8-bit scale factor... + validations: + required: true + + - type: textarea + id: vectorization + attributes: + label: Vectorization & Performance Verification + description: Confirm this can be implemented with pure PyTorch tensor operations without Python loops. + validations: + required: true + + - type: checkboxes + id: willingness + attributes: + label: Contribution Readiness + options: + - label: I am willing to implement this feature and submit a PR. + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..aecdfd3 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ +## Description + + +Fixes #(issue) + +## Type of Change + +- [ ] ๐Ÿ› Bug fix (non-breaking change fixing an issue) +- [ ] โœจ New feature (new quantization scheme, calibration algorithm, or packing format) +- [ ] โšก Performance optimization (vectorization speedup or memory compression) +- [ ] ๐Ÿ“š Documentation update (guides, docstrings, README) +- [ ] ๐Ÿงช Tests (coverage expansion or mathematical invariant verification) +- [ ] ๐Ÿ’ฅ Breaking change (fix or feature that breaks existing `QuantLinear` or packing contracts) + +## Quantization & Bit-Packing Invariants + +* **Precision Scheme**: (e.g. INT4 / INT8 / BitNet Ternary / FP8 / Ampere 2:4) +* **Packing Ratio**: `____ bits/weight` | `____ x compression vs FP16` +* **SQNR / Perplexity Impact**: `____ dB SQNR` | `____ perplexity on WikiText-2` + +## Architectural Invariants Checklist + +- [ ] **Exact Scalar & Tensor Roundtripping**: Packing and unpacking functions tested for bit-exact reconstruction within precision limits. +- [ ] **Pure PyTorch Vectorization**: Implemented with vectorized bitwise shifts/masks (`torch.bitwise_left_shift`, `torch.bitwise_right_shift`). Zero scalar loops over tensor elements. +- [ ] **Unit Tests & Coverage**: Ran `uv run python -m pytest` (100% pass rate, maintained >= 90% coverage). +- [ ] **Formatting & Linting**: Ran `uv run ruff check .` and `uv run ruff format --check .` with zero errors. +- [ ] **Documentation**: Updated `README.md` or docstrings if modifying CLI subcommands or quantization arguments. +- [ ] **Clean Commits**: Follows conventional commit format (`feat:`, `fix:`, `perf:`, `docs:`, `test:`). diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9a324be..c030c40 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,5 +31,8 @@ jobs: - name: Run linter run: uv run ruff check . + - name: Run format check + run: uv run ruff format --check . + - name: Run test suite with coverage run: uv run pytest diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..2b1493f --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,18 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-toml + - id: check-added-large-files + args: ["--maxkb=2000"] + - id: check-merge-conflict + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.9.3 + hooks: + - id: ruff + args: ["--fix"] + - id: ruff-format diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..2b16e77 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,43 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community maintainer at `prajwalpujari16@gmail.com`. All complaints will be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2ab8ab6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,31 @@ +# Security Policy ๐Ÿ”’ + +## Supported Versions + +| Version | Supported | +| :--- | :--- | +| `0.1.x` | :white_check_mark: | + +--- + +## Safe Tensor Guidelines + +1. **Pure Tensor Math**: `quantbench-engine` performs purely arithmetic bit-packing and matrix operations. It requires zero network connectivity. +2. **Safe Serialization**: Saved quantized checkpoints strictly serialize standard integer and float tensor dictionaries (`state_dict`). Untrusted pickle formats should never be loaded. + +--- + +## Reporting a Vulnerability + +If you discover a security vulnerability or numerical flaw that impacts host security: + +* **Please DO NOT file a public issue.** +* Report the issue privately through [GitHub's Private Vulnerability Reporting](https://github.com/Prajwal7-2002/quantbench/security/advisories/new) or email maintainer Prajwal Pujari at `prajwalpujari16@gmail.com`. + +### Submission Checklist +Please include: +1. Clear description of the vulnerability. +2. Minimal reproduction script. +3. Potential security impact. + +You will receive an acknowledgment within 48 hours, followed by updates on the fix and coordinated disclosure. diff --git a/uv.lock b/uv.lock index 3242197..bdd8c40 100644 --- a/uv.lock +++ b/uv.lock @@ -977,7 +977,7 @@ wheels = [ ] [[package]] -name = "quantbench" +name = "quantbench-engine" version = "0.1.0" source = { editable = "." } dependencies = [