docs: add Quickstart, honest comparison, and community-standards files

CODE_OF_CONDUCT.md

@@ -0,0 +1,38 @@
+# Code of Conduct
+
+This project adopts the **[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)** as its code of conduct. All contributors, maintainers, and participants in project spaces (issues, pull requests, discussions, and any associated channels) are expected to read and uphold it.
+
+The full text — including the pledge, standards, scope, enforcement guidelines, and attribution — is available at:
+
+> <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+We adopt that document by reference rather than re-inlining it so that any future clarifications or translations from the Contributor Covenant project flow through automatically.
+
+## Reporting a Concern
+
+If you experience or witness conduct that violates the Contributor Covenant in any project space, please report it privately:
+
+- **Email**: `affan.amir.mir@gmail.com` with subject prefix `[diff-cover-action conduct]`
+- **GitHub**: open a private security advisory at <https://github.com/Affanmir/diff-cover-action/security/advisories/new> and tag it `[conduct]`
+
+Reports are reviewed confidentially. Please include:
+
+- What happened (links to issues, PRs, comments, or screenshots)
+- Who was involved
+- Any prior context that may help
+
+You will receive an acknowledgement within 5 business days.
+
+## Enforcement
+
+The project maintainer ([@Affanmir](https://github.com/Affanmir)) is responsible for clarifying and enforcing this Code of Conduct, following the Enforcement Guidelines section of the linked Contributor Covenant. Possible responses range from a private warning to permanent ban from project spaces, depending on severity and pattern.
+
+The maintainer is also accountable to it. If you believe the maintainer has violated this Code of Conduct, please report it through the same channels above; an external mediator will be engaged if needed.
+
+## Scope
+
+This Code of Conduct applies in all project spaces — the GitHub repository, issue tracker, pull requests, discussions, and any official communication channel — and also when an individual is officially representing the project in public spaces.
+
+## Attribution
+
+This Code of Conduct is adopted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), maintained by the Contributor Covenant project and available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

CONTRIBUTING.md

@@ -1,10 +1,12 @@
 # Contributing to diff-cover-action
 
+Thanks for your interest in contributing! By participating, you agree to abide by the project's [Code of Conduct](CODE_OF_CONDUCT.md). For security issues, please follow the private reporting process in [SECURITY.md](SECURITY.md) instead of opening a public issue.
+
 ## Development Setup
 
 ```bash
 # Clone the repo
-git clone https://github.com/your-org/diff-cover-action.git
+git clone https://github.com/Affanmir/diff-cover-action.git
 cd diff-cover-action
 
 # Install dev dependencies

README.md

@@ -12,24 +12,58 @@ A GitHub Action that wraps [diff-cover](https://github.com/Bachmann1234/diff_cov
 
 ---
 
-## Why This Action?
-
-| | diff-cover-action | Codecov | Coveralls | coverage-diff |
-|---|:---:|:---:|:---:|:---:|
-| **Free & self-hosted** | Yes | Freemium | Freemium | Yes |
-| **No external account** | Yes | No | No | Yes |
-| **Coverage + quality in one** | Yes | No | No | No |
-| **13+ lint tools** (ruff, eslint, mypy...) | Yes | No | No | No |
-| **PR comments** | Yes | Yes | Yes | Yes |
-| **Inline annotations** | Yes | Yes | Yes | No |
-| **Step summaries** | Yes | No | No | No |
-| **Badge generation** | Yes | Yes | Yes | Yes |
-| **JaCoCo / lcov / XML** | Yes | Yes | Yes | JSON only |
-| **Shallow clone handling** | Auto | Manual | Manual | N/A |
-| **Fork PR safe** | Yes | Yes | Yes | Limited |
-| **Data stays in your CI** | Yes | No | No | Yes |
-
-**In short**: This is the only action that does **both** diff coverage and diff quality analysis in a single step, with full GitHub integration, across any language and linter -- with zero vendor dependencies.
+## Quickstart in 60 seconds
+
+Drop this file into `.github/workflows/diff-coverage.yml`, push, and open a PR. A coverage comment will appear automatically — no signup, no token, no external service.
+
+```yaml
+name: Diff Coverage
+on: [pull_request]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install pytest pytest-cov && pytest --cov --cov-report=xml
+      - uses: Affanmir/diff-cover-action@v2
+        with:
+          coverage-files: coverage.xml
+```
+
+That's the whole setup. It works on **any language** that produces Cobertura XML, lcov, or JaCoCo — replace the `pytest` line with your own test command (Jest, `go test -coverprofile`, Maven, etc.). For thresholds, monorepos, fork PRs, or quality (lint) mode, see [Common Patterns](#common-patterns) below.
+
+---
+
+## How does this compare?
+
+Honest comparison — `diff-cover-action` is not always the right pick. Here's where each tool wins:
+
+| | diff-cover-action | Codecov | Coveralls | 5monkeys/cobertura-action |
+|---|---|---|---|---|
+| **Setup** | 1 workflow file | App install + token | App install + token | 1 workflow file |
+| **Where it runs** | Your CI runner | SaaS (data uploaded) | SaaS (data uploaded) | Your CI runner |
+| **Pricing** | Free (OSS, MIT) | Free for OSS, paid private | Free for OSS, paid private | Free (OSS, MIT) |
+| **Coverage scope** | Changed lines only | Full repo + diff | Full repo + diff | Changed lines only |
+| **Lint / quality reporting** | 13+ tools (ruff, eslint, mypy, …) | — | — | — |
+| **PR comment** | Idempotent updates | Idempotent updates | Idempotent updates | Idempotent updates |
+| **Inline diff annotations** | Yes | Yes | Yes | — |
+| **Actions step summary** | Yes | — | — | — |
+| **Historical trend graphs** | — | Yes | Yes | — |
+| **Org-wide dashboards** | — | Yes | Yes | — |
+| **Coverage formats** | Cobertura XML, lcov, JaCoCo, Clover | Cobertura, lcov, JaCoCo, +many | Cobertura, lcov, +many | Cobertura XML only |
+| **Fork PR comments** | Skips gracefully (read-only token) | Works via app token | Works via app token | Skips gracefully |
+| **Data leaves your CI?** | No | Yes | Yes | No |
+
+**Pick `diff-cover-action` if** you want diff coverage *and* diff quality (lint) in one step, you don't want vendor signups, and you don't need cross-PR trend history.
+
+**Pick Codecov / Coveralls if** you need historical trend graphs, organization dashboards, full-repo coverage tracking on non-PR commits, or coverage history retained outside CI logs.
+
+**Pick `5monkeys/cobertura-action` if** all you need is a Cobertura PR comment and you don't care about lint/quality, lcov, or JaCoCo.
 
 ---
 
@@ -157,7 +191,7 @@ The same coverage table also appears in the **Actions > Job Summary** tab so you
 
 ---
 
-## Quick Start
+## Common Patterns
 
 ### Coverage Mode
 
@@ -487,7 +521,11 @@ Report coverage without failing the step:
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines. Participation in this project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Found a vulnerability? Please report it privately — see [SECURITY.md](SECURITY.md) for the reporting policy and supported versions.
 
 ## License
 

SECURITY.md

@@ -0,0 +1,66 @@
+# Security Policy
+
+`diff-cover-action` runs inside your GitHub Actions workflow with access to your repository content and a `GITHUB_TOKEN`. We take security reports seriously and ask that you report them privately so we can fix issues before they are publicly disclosed.
+
+## Supported Versions
+
+Only the latest major version receives security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| `v2.x`  | :white_check_mark: |
+| `v1.x`  | :x: (please upgrade) |
+
+The major-version tag (`@v2`) is moved on each compatible release, so pinning to `@v2` automatically receives security patches. Pinning to a SHA is supported and recommended for hardened environments — see the [release notes](https://github.com/Affanmir/diff-cover-action/releases) for the SHA of each version.
+
+## Reporting a Vulnerability
+
+**Please do not open a public GitHub issue for security reports.**
+
+Use one of the following private channels:
+
+1. **GitHub Security Advisory (preferred)** — open a private report at <https://github.com/Affanmir/diff-cover-action/security/advisories/new>. This keeps the discussion private and lets us coordinate a fix and release together.
+2. **Email** — `affan.amir.mir@gmail.com` with the subject prefix `[diff-cover-action security]`.
+
+Please include:
+
+- A description of the vulnerability and its impact
+- Steps to reproduce (a minimal repo or workflow snippet helps)
+- Affected version(s) or commit SHA
+- Any suggested mitigation, if you have one
+
+## What to Expect
+
+- **Acknowledgement**: within 5 business days.
+- **Initial assessment**: within 10 business days, including whether we consider the report in scope and a rough remediation timeline.
+- **Fix and release**: severity-dependent. Critical issues are prioritised; lower-severity issues are bundled into the next regular release.
+- **Public disclosure**: typically once a fix has shipped and downstream users have had a reasonable upgrade window (target: 30 days after release for high/critical, sooner for low-impact). We will credit the reporter unless anonymity is requested.
+
+This is a solo-maintained open-source project — response times are best-effort, not contractual.
+
+## Scope
+
+**In scope**
+
+- The action code in this repository (`src/`, `entrypoint.py`, `action.yml`, `Dockerfile`, `templates/`)
+- The published Docker image used at runtime
+- Direct dependencies declared in `requirements.txt`
+- Documentation that could mislead users into an insecure configuration
+
+**Out of scope**
+
+- Vulnerabilities in transitive dependencies that have no exploitable path through this action (please report those upstream)
+- Misconfiguration in *consumer* workflows (e.g. a user passing `pull_request_target` with insufficient hardening); we will document safer patterns but cannot patch them centrally
+- Issues in [`diff_cover`](https://github.com/Bachmann1234/diff_cover) itself — please report upstream
+- Denial-of-service via unbounded user input that only impacts the user's own runner
+
+## Hardening Recommendations for Consumers
+
+If you are using this action in security-sensitive workflows:
+
+- Pin to a commit SHA (`uses: Affanmir/diff-cover-action@<sha>`) rather than a moving tag
+- Grant the minimum required permissions (`contents: read`, `pull-requests: write`)
+- Avoid `pull_request_target` unless you understand the [security implications](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/)
+- Review the [release notes](https://github.com/Affanmir/diff-cover-action/releases) before upgrading the major-version tag
+
+Thank you for helping keep `diff-cover-action` and its users safe.