README.md

Footprint

Footprint is an OSS contributions impact scoring engine that discovers your public GitHub contributions, scores them by real impact, and generates portfolio-ready artifacts — SVG cards, a structured JSON report, and a Markdown summary.

It goes beyond raw commit or PR counts. Contributions are weighted by type, boosted if merged, scaled by repository popularity, and decayed for repetitive low-effort activity. The card is a projection of that model.

---

How Scoring Works

Every contribution earns a base score:

Contribution	Base Score
Pull Request	10.0
Issue	5.0
Code Review	3.0
Issue Comment	2.0
Discussion	2.0
Discussion Comment	2.0
Review Comment	1.0

Three modifiers are applied:

• Merged PR Bonus — merged PRs receive a 1.5× multiplier on their base score, applied before popularity.
• Repo Popularity Multiplier — each repo's score is scaled by 1 + log10(1 + stars + 2×forks), capped at 4.0×. Forks are weighted 2× as a higher-intent adoption signal. The log scale prevents star-heavy repos from overwhelming everything else.
• Diminishing Returns — comment-type contributions (issue comments, review comments, PR comments, discussion comments) decay per repo using 1.0 / (1.0 + 0.5 × count). The first comment scores at 1.0×, the second at 0.66×, the third at 0.5×, and so on. Consistent engagement is valued; pure volume is not.

---

Card Variants

Variant	Stats	Sections	Hides zeros
Standard	All	—	No
Minimal	Non-zero only	—	Yes
Extended	All	Owned projects + top contributions	No
Extended Minimal	Non-zero only	Owned projects + top contributions	Yes

Standard	Minimal

Extended	Extended Minimal

---

GitHub Action Usage

Add this workflow to any repository — typically your username/username profile repo:

# .github/workflows/footprint.yml
name: Generate Footprint

on:
    schedule:
        - cron: "0 0 * * 0" # Weekly on Sunday
    workflow_dispatch:

permissions:
    contents: write # Required to push artifacts to output branch

jobs:
    generate:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4

            - name: Generate Footprint
              uses: arayofcode/footprint@v1
              env:
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The default GITHUB_TOKEN is sufficient. No PAT required.

Inputs

Input	Default	Description
gh_token	${{ github.token }}	GitHub token for API access
username	GITHUB_ACTOR	GitHub username to profile (defaults to the repo owner)
output_branch	footprint-output	Branch where generated artifacts are committed
output_dir	dist	Local output directory inside the container
min_stars	0	Minimum star count for a project to appear in card sections. Does not affect aggregate stats — all owned projects are always counted
card	true	Generate SVG card variants
timeout	300	Timeout for GitHub API operations in seconds. Raise this for prolific contributors

Outputs

Output	Description
total_contributions	Count of discovered external contributions
owned_projects_count	Count of owned projects meeting the star threshold
total_score	Aggregate weighted impact score

Generated Artifacts

Artifacts are committed to output_branch after each run:

File	Description
card.svg	Standard card — all stats
card-minimal.svg	Minimal card — non-zero stats only
card-extended.svg	Extended card — stats + repo sections
card-extended-minimal.svg	Extended minimal — non-zero stats + sections
report.json	Full structured scoring data (schema versioned)
summary.md	Human-readable impact summary, also written to the Actions job summary

---

Embedding in Your Profile README

Markdown

![Footprint Card](https://raw.githubusercontent.com/<username>/<repo>/footprint-output/card.svg)

HTML (with link)

<a href="https://github.com/<username>/<repo>">
    <img
        src="https://raw.githubusercontent.com/<username>/<repo>/footprint-output/card-extended.svg"
        alt="Footprint"
        width="800"
    />
</a>

Tip

Replace <username>/<repo> with the repository where you added the workflow (e.g. arayofcode/arayofcode). The branch is footprint-output by default.

---

Local Usage

export GITHUB_TOKEN=your_token
go run ./cmd/footprint -username <github_username>

Optional flags:

Flag	Default	Description
-username	GITHUB_ACTOR	GitHub username
-min-stars	0	Minimum stars for owned projects
-output	dist	Output directory
-timeout	300s	API timeout
-card	true	Generate SVG cards