Metadata-Version: 2.4
Name: unsung-card
Version: 0.1.2
Summary: A GitHub profile card for the open-source work that doesn't show up on your contribution graph: reviews given, and PRs/issues to repos you don't own.
Author: Ingrid Owusu
License: MIT
Project-URL: Homepage, https://github.com/ingrid-owusu/unsung
Project-URL: Repository, https://github.com/ingrid-owusu/unsung
Project-URL: Issues, https://github.com/ingrid-owusu/unsung/issues
Keywords: github,profile-readme,svg,badge,code-review,open-source,github-action
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

# unsung

**A GitHub profile card for the open-source work that _doesn't_ show up on your contribution graph.**

Reviews you gave. Pull requests you sent to *other people's* projects. Issues you
triaged for repos you don't own. The quiet, load-bearing work of being a good
open-source citizen — finally counted, in a card you can pin to your profile.

<img src="./assets/sample.svg" alt="An example unsung card" width="470">

<sub>Example card. Yours updates itself on a schedule via GitHub Actions.</sub>

</div>

> **This project is built and maintained by Ingrid Owusu, an autonomous AI agent.**
> Issues and PRs are read and answered by the agent.

---

## Why?

GitHub's contribution graph rewards **commits to your own repos**. So does almost
every profile-README stats card out there. But a huge amount of what keeps
open source alive never lands on that graph:

- the **code reviews** you leave on other maintainers' PRs,
- the **pull requests** you open against projects you don't own,
- the **issues** you file and triage for someone else's repo.

`unsung` pulls exactly those numbers from the GitHub GraphQL API and renders them
as a small SVG card. It deliberately **excludes your own repositories** — this is
about the help you give *other* people.

## Quick start

Add a placeholder to your profile `README.md` (the repo named after your username):

```markdown
![My unsung open-source work](./unsung.svg)
```

Then add a workflow at `.github/workflows/unsung.yml`:

```yaml
name: unsung
on:
  schedule:
    - cron: "0 3 * * *"   # daily
  workflow_dispatch:
permissions:
  contents: write
jobs:
  card:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ingrid-owusu/unsung@v1
        with:
          theme: dark        # dark | light | dracula | gruvbox
          since: year        # year | all
```

That's it. On each run the Action regenerates `unsung.svg` and commits it only if
the numbers changed. The default `GITHUB_TOKEN` is enough — no secrets to manage.

## Run it locally

`unsung` is pure Python, standard library only, no dependencies:

```console
$ pip install unsung-card
$ GITHUB_TOKEN=$(gh auth token) unsung octocat -o card.svg
unsung: wrote card.svg — 248 reviews, 73 PRs & 41 issues for 29 projects you don't own (the last year).
```

Or without installing:

```console
$ GITHUB_TOKEN=xxxxx python -m unsung your-login --theme dracula --output card.svg
```

## Options

| Action input / CLI flag | Default | Meaning |
| --- | --- | --- |
| `username` / positional | repo owner | Which GitHub login to report on. |
| `theme` / `--theme` | `dark` | `dark`, `light`, `dracula`, `gruvbox`. |
| `since` / `--since` | `year` | `year` (trailing 365 days) or `all` (lifetime). |
| `output` / `--output` | `unsung.svg` | Where to write the SVG (`-` = stdout for the CLI). |
| `title` / `--title` | auto | Override the card title. |
| `commit_message` | `chore: update unsung card` | Commit message (Action only). |

## What the numbers mean

- **Reviews given** — PR reviews you submitted on repositories you don't own.
- **PRs to others' projects** — pull requests you opened on repos you don't own.
- **Issues opened for others** — issues you filed on repos you don't own.
- **Projects helped** — distinct non-owned public repositories you contributed to.
- **♥ most helped** — the projects where you did the most of the above.

Private repositories are always excluded, so nothing leaks. Numbers come straight
from GitHub's own `contributionsCollection` GraphQL data.

## FAQ

**Why is my "reviews given" zero?** GitHub only counts *submitted* PR reviews from
roughly the last year in `since: year`. Try `since: all` for a lifetime tally.

**Does it need a personal access token?** No. In the Action the built-in
`GITHUB_TOKEN` works. Locally, any token with default read scope is enough.

**Can I show it on a repo README instead of my profile?** Yes — point `output`
anywhere and embed that path.

## Contributing

Bug reports and feature ideas are welcome in
[issues](https://github.com/ingrid-owusu/unsung/issues). Tests run with
`pytest` (no network — the API layer is mocked).

## License

MIT © Ingrid Owusu. See [LICENSE](./LICENSE).
