diff --git a/README.md b/README.md index 8672b0f..20eaa66 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,25 @@ pack): --- +## Contributors + +CV Builder is **community-built**. Every merged contribution — code, docs, +rules, archetypes, tests, research, design feedback, issue triage, and +honest reviews — came from someone who chose to spend their time on it. + +- **[Contributors](docs/CONTRIBUTORS.md)** — human-first recognition for + everyone who has shaped the project so far. +- **[Contribution Snapshot](docs/CONTRIBUTION_SNAPSHOT.md)** — the + numbers behind the recognition (as of 2026-07-02). +- **[GitHub contributors graph](https://github.com/TechImmigrants/cv-builder/graphs/contributors)** — + the live view. + +If you contributed and don't see your name, please open a PR correcting +[`docs/CONTRIBUTORS.md`](docs/CONTRIBUTORS.md) — the file is intentionally +easy to edit. + +--- + ## Research Our rules are backed by data, not vibes. See: diff --git a/docs/CONTRIBUTION_SNAPSHOT.md b/docs/CONTRIBUTION_SNAPSHOT.md new file mode 100644 index 0000000..866e0c6 --- /dev/null +++ b/docs/CONTRIBUTION_SNAPSHOT.md @@ -0,0 +1,222 @@ +# Contribution Snapshot + +> A generated-style snapshot of contributor activity for CV Builder, as of +> the date below. This is a **statistical view**, not a leaderboard. +> Numbers are imperfect and should be read with the caveats at the bottom. +> +> For human-first recognition, see [`docs/CONTRIBUTORS.md`](./CONTRIBUTORS.md). + +## Snapshot metadata + +| Item | Value | +| --- | --- | +| Date generated | 2026-07-02 | +| Repository | [TechImmigrants/cv-builder](https://github.com/TechImmigrants/cv-builder) | +| Branch reviewed | `main` | +| Commit hash | `4b4bb03` (post-PR #88 docs audit + PR #92 archetype gap audit) | +| Period covered | Project inception → 2026-07-02 | + +## Merged pull requests + +Pull requests reviewed for this snapshot via `gh pr list --state merged +--limit 100`. + +| Metric | Value | +| --- | --- | +| Total merged PRs | 28 | +| Distinct merged-PR authors | 10 | +| Closed-not-merged PRs | 4 | +| Open PRs (intentionally untouched) | 3 (#37, #78, #89 at snapshot time) | + +### Contributors by merged-PR count + +Provided for context, **not** as a ranking. + +| Rank | GitHub login | Merged PRs | Example areas | +|---|---|---:|---| +| 1 | `amirbahador-hub` | 9 | foundation stack (schemas, intelligence, prompts, eval harness, power-user pack) | +| 2 | `SaharPak` | 8 | MVP integration, MVP release polish, no-code paths, docs audit, archetype gap audit | +| 3 | `heerrpanchal` | 3 | universal rules (CV length, date format, education-first layout) | +| 4 | `alexNJF` | 2 | web UI input screen, dark / light mode | +| 5 | `IKetutWidiyane` | 1 | AI Product Manager + ML Engineer archetypes | +| 5 | `davido-noowin` | 1 | outdated-technologies rule | +| 5 | `rfatideh` | 1 | web project init | +| 5 | `ded-furby` | 1 | Windows setup guide | +| 5 | `nanookclaw` | 1 | CLI `--format json` | +| 5 | `Mohammadreza-Sarvari` | 1 | QA / Test Engineer archetype | + +### Closed-not-merged PRs (still meaningful) + +| GitHub login | Closed PR | Why closed | +|---|---|---| +| `guteeeeeeeee` | #55 — flag missing contact information | Rule already present in evaluator; merging would duplicate detection. | +| `IKetutWidiyane` | #39 — ML Engineer archetype | Subsumed by PR #84 (which adds the same archetype plus AI Product Manager). | +| `SaharPak` | #36 — Phase 1 team structure | Subsumed by PR #73 + PR #79 docs pass. | +| `milad-i` | #35 — Added Web-UI | Superseded by PR #76 + the existing `apps/web-ui` skeleton. | + +These contributions are still recognised in [`docs/CONTRIBUTORS.md`](./CONTRIBUTORS.md). + +### Open PRs + +| GitHub login | PR | What it adds | Status | +|---|---|---|---| +| `riddhij-7` | #37 | CLI color output | Author needs to rebase against post-merge `main`; CLI was refactored after the PR opened. Intentionally untouched in this snapshot. | +| `Isusami` | #78 | Cloudflare Pages previews for the web UI | Requires `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` secrets; needs maintainer with repo admin access. Intentionally untouched. | +| `SaharPak` | #89 | Contributor recognition docs (this work) | Open at snapshot time. | + +## Commits on `main` + +Pulled from `git shortlog -sn` and the GitHub contributors API +(`/repos/TechImmigrants/cv-builder/contributors`). Numbers disagree by +source because the API counts only commits on the default branch and +merges them by GitHub account, while `git shortlog` counts commits on the +checked-out branch by raw author name. + +### `git shortlog -sn --all` + +| Commits | Author | Notes | +|---:|---|---| +| 30 | AmirBahador Bahadori | Foundation stack; same person as `amirbahador-hub` | +| 26 | Cleanup Bot | Local-only git author used during PR #85 integration. **Not a human contributor**; excluded from recognition. (GitHub API counts 22 on `main`; the extra 4 live on non-merged branches. `--all` includes everything reachable.) | +| 13 | a.hakimi | Dark mode / theme / input form work; see attribution caveat below | +| 11 | Sahar | Same person as `SaharPak` (different local author name) | +| 8 | SaharPak | Maintainer | +| 7 | amirbahador | Same person as `AmirBahador Bahadori` (different local author name) | +| 6 | Sam | Local name on the merge commit for dark-mode PR #58; not necessarily the same person as `Isusami` | +| 5 | David Nguyen | Same person as `davido-noowin` | +| 4 | Heer Panchal | Same person as `heerrpanchal` | +| 4 | Ketut Widiyane | Same person as `IKetutWidiyane` | +| 3 | IKetutWidiyane | | +| 3 | Sahar Pakseresht | Same person as `SaharPak` (different local author name) | +| 2 | Reza Fatideh | Same person as `rfatideh` | +| 2 | guteeeeeeeee | | +| 1 | Heer | Same person as `heerrpanchal` | +| 1 | Mohammadreza Sarvari | | +| 1 | Nanook | Same person as `nanookclaw` | +| 1 | ded-furby | | + +### GitHub contributors API + +Top contributors by commits linked to a public GitHub account on +`main`. + +| GitHub login | Commits on `main` | +|---|---:| +| `SaharPak` | 18 | +| `amirbahador-hub` | 7 | +| `IKetutWidiyane` | 7 | +| `davido-noowin` | 5 | +| `rfatideh` | 2 | +| `heerrpanchal` | 1 | +| `nanookclaw` | 1 | +| `Isusami` | 1 | +| `ded-furby` | 1 | + +Anonymous commits on `main` (no GitHub link): + +| Author | Commits | +|---|---:| +| AmirBahador Bahadori | 30 | +| a.hakimi | 13 | +| Heer Panchal | 4 | +| Sahar Pakseresht | 3 | +| Cleanup Bot | 22 (excluded from recognition — see caveats) | +| Mohammadreza Sarvari | 1 | + +## Notable contribution areas + +| Area | Primary contributors | +|---|---| +| Zod contract (`packages/schemas`) | `amirbahador-hub` | +| Rubric, archetypes, validators (`packages/intelligence`) | `amirbahador-hub`, `IKetutWidiyane`, `Mohammadreza-Sarvari` | +| Prompt pack (`packages/prompts`) | `amirbahador-hub` | +| Power-user Claude Code skill (`apps/cli`) | `amirbahador-hub` | +| Core engine / rules (`packages/core`) | `heerrpanchal`, `davido-noowin` | +| Eval harness + golden fixtures (`packages/eval`) | `amirbahador-hub` | +| Web UI (`apps/web-ui`) | `alexNJF`, `a.hakimi` (anonymous commits), `rfatideh` | +| CLI (`packages/cli`) | `nanookclaw`, `riddhij-7` (open PR #37) | +| Windows onboarding docs | `ded-furby` | +| Docs / roadmap / MVP release | `SaharPak`, `amirbahador-hub` | +| Docs consistency audit | `SaharPak` (PR #88) | +| Archetype gap audit | `SaharPak` (PR #92) | +| Cloudflare Pages previews (open PR #78) | `Isusami` | + +## Caveats — please read these before drawing conclusions + +1. **Counts are imperfect.** `git shortlog` and the GitHub contributors + API use different definitions of "contributor" and disagree in places. + The numbers above are the best-effort combination of both. +2. **PR count ≠ contribution size.** A 5-line rule PR and a 500-line + foundation PR both count as one. Do not infer effort from this + table. +3. **Commit count ≠ contribution size.** Bulk reformatting, auto-generated + dependency bumps, and a single careful bug fix can all show up as + "one commit." Context matters; this table does not capture it. +4. **Anonymous committers are real people.** Several dark-mode and + CV/JD input commits on `main` are authored by `a.hakimi` (local git + author name) without a resolvable GitHub account. The work is real; + the attribution is noisy. +5. **Local git author names vary.** The same person can appear under + several names in `git shortlog` (e.g., `Sahar`, `SaharPak`, + `Sahar Pakseresht`). This snapshot collapses them where the link is + clear and flags the uncertainty otherwise. +6. **Issue-only contributors are not in these counts.** The issue + tracker is a major contribution surface; this snapshot doesn't yet + count it. As community testing begins we'll add a per-issue section + here. +7. **Counts do not capture review, discussion, product thinking, or + community support.** Reading a draft and pushing back on a design + call, triaging an issue, answering a question in `#feedback`, or + helping a newcomer install pnpm don't show up in this table. They + are part of who built the project and are listed (without counts) + in [`docs/CONTRIBUTORS.md`](./CONTRIBUTORS.md). +8. **Cleanup Bot** is excluded from recognition. It's a local git + author name used during the post-PR #85 integration pass to + batch-attribute cleanup commits; not a human contributor. +9. **The "open PR" column is intentionally shown** so it's clear that + those contributors haven't been excluded — they're just awaiting + either a rebase (#37) or secrets provisioning (#78). Both are + listed in [`docs/CONTRIBUTORS.md`](./CONTRIBUTORS.md). + +--- + +## How to refresh this snapshot + +```bash +# From the repo root +git checkout main +git pull origin main + +# Merged PRs by author +gh pr list --state merged --limit 200 \ + --json number,title,author,mergedAt,labels \ + | jq -r '.[] | [.author.login, .number, .title] | @tsv' \ + | sort + +# Closed-not-merged PRs by author +gh pr list --state closed --limit 200 \ + --json number,title,author,mergedAt \ + | jq -r '.[] | select(.mergedAt == null) | [.author.login, .number, .title] | @tsv' + +# Commits on main, grouped by author +git shortlog -sn main + +# GitHub contributors (counts commits on default branch) +gh api repos/TechImmigrants/cv-builder/contributors?anon=true \ + | jq -r '.[] | "\(.contributions)\t\(.login // .name)"' + +# Anonymous contributors +# Names only — emails from the contributors API are private contact +# information and should not be published in this repo. +gh api repos/TechImmigrants/cv-builder/contributors?anon=true \ + | jq -r '.[] | select(.type == "Anonymous") | "\(.contributions)\t\(.name)"' +``` + +Refresh the numbers in this file in the same PR that updates +[`docs/CONTRIBUTORS.md`](./CONTRIBUTORS.md). + +--- + +*Generated 2026-07-02. Snapshot is automatic in spirit but hand-curated +for accuracy; numbers above were checked against both the GitHub API and +the local git history at the date noted.* \ No newline at end of file diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md new file mode 100644 index 0000000..24334f5 --- /dev/null +++ b/docs/CONTRIBUTORS.md @@ -0,0 +1,247 @@ +# Contributors + +> CV Builder is **community-built**. Every merged contribution — code, docs, +> rules, archetypes, tests, research, design feedback, issue triage, and +> honest reviews — came from someone who chose to spend their time on it. +> This page is a **thank-you**, not a leaderboard. +> +> If you contributed and you don't see your name, or if something is wrong, +> please open an issue or a PR correcting this file. We update it as part +> of every release. +> +> Snapshot stats: see [`docs/CONTRIBUTION_SNAPSHOT.md`](./CONTRIBUTION_SNAPSHOT.md). +> +> Last refreshed: 2026-07-02, against `main` at `4b4bb03` (post-PR #87 MVP +> release + PR #88 docs audit + PR #92 archetype gap audit). + +--- + +## Maintainers + +The people currently responsible for the project's direction, releases, +and community health. + +- **[@SaharPak](https://github.com/SaharPak)** — *Sahar Pakseresht.* Project + lead and product owner. Owns the MVP scope, the roadmap, the release + process, and the public docs. Author of the no-code contribution guide, + the MVP demo plan, the post-merge validation reports, the MVP release + status doc, the docs-consistency audit (PR #88), and the role-archetype + gap audit (PR #92). + +--- + +## Code contributors + +The people who wrote the production code that runs today. Listed in the +order they merged their first meaningful PR — not by line count or PR count. + +### Foundation stack — the layers underneath every surface + +- **[@amirbahador-hub](https://github.com/amirbahador-hub)** — *AmirBahador + Bahadori.* Built the foundational packages that power the MVP: + `@cv-builder/schemas` (Zod contract, PR #68), `@cv-builder/intelligence` + (rubric v1, archetypes, validators — PR #69), `@cv-builder/prompts` + (extract / score / validate-claims prompt pack — PR #70), the power-user + Claude Code skill (PR #71), and the `@cv-builder/eval` golden-fixture + harness (PR #72). Also wrote the power-user quickstart in `apps/cli/` + and the project structure doc (PR #73). Nine merged PRs and the bulk of + the evaluator's first working tree. + +### Web UI + +- **[@alexNJF](https://github.com/alexNJF)** — Authored the CV + JD + input screen with file upload and client-side evaluation (PR #76), which + became the MVP web UI shipped in PR #85. Also authored the dark / light + mode toggle (PR #58). Several of the underlying commits in those PRs + were authored by `a.hakimi` (see the attribution note at the bottom). + +- **`a.hakimi`** *(local git author name, no public GitHub link; + 13 commits on `main`)* — Authored most of the underlying implementation + for the dark / light theme system (next-themes integration, Header, + ThemeToggle, theme-aware styles) and the CV/JD input form that landed + via PRs #58 and #76. We couldn't link these commits to a public GitHub + account from the local git author metadata; if this is you, please open + an issue and we'll add a real profile link. + +- **[@rfatideh](https://github.com/rfatideh)** — *Reza Fatideh.* Initialised + the web project structure (PR #56). + +### Rules — small engines that add up + +- **[@heerrpanchal](https://github.com/heerrpanchal)** — *Heer Panchal.* + Authored three rules in close succession: CV length via word-count + heuristic (PR #27), inconsistent date-format detection (PR #29), and + education-first layout detection (PR #30). Together these are some of + the highest-value universal rules in the evaluator. + +- **[@davido-noowin](https://github.com/davido-noowin)** — *David Nguyen.* + Authored the outdated-technologies rule (PR #74), with the supporting + regex work in `packages/core/src/rules/`. Also handled the biome format --write . formatting pass during integration. + +### Archetypes — the role-specific scoring configuration + +- **[@IKetutWidiyane](https://github.com/IKetutWidiyane)** — *Ketut + Widiyane.* Authored the AI Product Manager archetype (PR #84) and the + Machine Learning Engineer archetype (which closed PR #39 as a + duplicate). Two of the seven roles the MVP ships with. + +- **[@Mohammadreza-Sarvari](https://github.com/Mohammadreza-Sarvari)** — + *Mohammadreza Sarvari.* Authored the QA / Test Engineer archetype + (PR #28), one of the seven shipped roles. + +### CLI + +- **[@nanookclaw](https://github.com/nanookclaw)** — *Nanook.* Authored the + `--format json` flag for the CLI evaluator (PR #38). The eval harness + relies on this for its golden-fixture assertions. + +- **[@riddhij-7](https://github.com/riddhij-7)** — *Open contribution.* + Authored `feat(cli): add color output for scores, dimensions, and issues` + (PR #37). Currently open and intentionally not merged yet; the CLI was + refactored after the PR opened, so the author needs to rebase before + it can land. Either way — thank you for the contribution. + +### Infrastructure + +- **[@Isusami](https://github.com/Isusami)** — *Sam.* Authored + `ci(web-ui): deploy previews to Cloudflare Pages` (PR #78). Currently + open and intentionally not merged; the project does not yet have a + hosted deployment. When the maintainer provisions the Cloudflare + account and secrets, this PR will land. + +--- + +## Docs and roadmap contributors + +- **[@SaharPak](https://github.com/SaharPak)** — *Sahar Pakseresht.* The + no-code contribution guide and `ROADMAP.md` (PR #79), the MVP demo + plan, the post-merge validation report, the PR #85 rollback plan, the + remaining-PRs plan, the MVP release status doc, the docs-consistency + audit (PR #88), and the role-archetype gap audit (PR #92). + +- **[@amirbahador-hub](https://github.com/amirbahador-hub)** — Power-user + quickstart and project structure documentation (PR #73). + +- **[@ded-furby](https://github.com/ded-furby)** — *Windows contributor + setup guide* (PR #54). The repo's only first-class Windows onboarding + doc; an important inclusion for non-macOS / non-Linux contributors. + +- **[@milad-i](https://github.com/milad-i)** — *Early Web UI scaffolding.* + PR #35 was closed during the cleanup phase as superseded by PR #76, but + it informed the eventual MVP shape. Thank you for the early work. + +--- + +## Testing / QA contributors + +There aren't dedicated QA contributors yet (most testing has shipped +alongside the rules and the eval harness). The people who built the +test infrastructure are: + +- **[@amirbahador-hub](https://github.com/amirbahador-hub)** — + `@cv-builder/eval` golden-fixture harness (PR #72). Five fixture + scenarios (`swe-strong`, `swe-weak-table`, `swe-with-jd`, `pm-strong`, + `data-ml-strong`) that catch regressions in archetype detection and + ATS verdict. +- **[@heerrpanchal](https://github.com/heerrpanchal)** — Each rule + shipped with its own test coverage. +- **[@SaharPak](https://github.com/SaharPak)** — Integration cleanup that + brought the rule tests and the eval fixtures into the same suite + (PR #85). + +If you want to contribute on the QA axis specifically, the +[`good first issue`](https://github.com/TechImmigrants/cv-builder/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +list has rule-test additions and fixture expansions. + +--- + +## Product and community feedback contributors + +People who shaped what the MVP became through issues, design feedback, +and review. The issue tracker is the main surface here. + +- **The community members who opened and triaged GitHub issues.** This + is the largest contribution surface by far and the easiest to + under-count. Issues filed against the MVP during the public-testing + phase directly shaped the polish PR #87 (home page copy, results page, + file upload behaviour, empty states, scoring colour thresholds, etc.). +- **The community reviewers who commented on drafts.** Thank you for + reading carefully and pushing back when the copy was wrong. +- **The anonymous contributors who tested the binary locally and + reported what worked and what didn't.** Without you, the polish + priorities would have been guesses. + +If you want to contribute at this layer — and the project's docs +[CONTRIBUTING.md](../CONTRIBUTING.md) calls it out as one of the +highest-leverage ways to help — pick an open issue, read it carefully, +and write a thoughtful comment. That's it. + +--- + +## Special thanks + +- **CodeRabbit** — automated PR review. Caught several real issues + before merge (defensive localStorage parsing in + `apps/web-ui/src/app/results/page.tsx`, schema/doc drift in + `docs/LOCAL_DEMO.md`, and the React-state vs imperative-DOM choice + in `apps/web-ui/src/app/components/FileUpload.tsx`). +- **The Tech Immigrants community** — for hosting this project and for + being the reason it exists. Specifically the `#feedback` channel, + which is the project's primary community surface. +- **cvroast.dev** — the original deployed product this project + rebuilt on a proper architecture. The MVP's rubric is informed by + what worked in production there. + +--- + +## Attribution caveats + +A few things we want to be transparent about: + +1. **Commit counts are imperfect.** `git shortlog` and the GitHub + contributors API disagree in places because some commits land via + merge commits (which credit the merger, not the original author) and + some PRs have multiple local git author names that don't link back to + a single GitHub account. +2. **PR count ≠ contribution size.** A 5-line rule and a 500-line + foundation package both count as one merged PR. We deliberately do + not rank by either. +3. **Counts do not capture review, discussion, product thinking, or + community support.** Reading a draft and pushing back on a design + call, triaging an issue, answering a question in `#feedback`, or + helping a newcomer install pnpm all shape the project but don't show + up as merged PRs or commits. They're why the *Product and community + feedback contributors* section above is not quantified. +4. **`a.hakimi` is anonymous in our data.** Several dark-mode and + CV/JD input commits on `main` are authored by `a.hakimi` (local git + author name, no resolvable GitHub username). The web UI work is + credited to `alexNJF` (the PR author), but a meaningful chunk of the + underlying implementation came from `a.hakimi`. +5. **Cleanup Bot** appears in commit history. It's a local git author + name used during the post-PR #85 integration pass to batch-attribute + cleanup commits; it is not a human contributor and is excluded from + recognition. +6. **Issue-only contributors are real contributors.** They are harder + to credit individually because the project is small enough that most + issues are filed by the maintainer during seeding. As community + testing begins, we'll add named issue contributors here. +7. **If we missed you, please tell us.** Open a PR correcting this + file. We'll merge it. + +--- + +## How to add yourself + +If you contributed something the project should know about: + +1. Open a PR against `main` titled `docs: add to + CONTRIBUTORS`. +2. Add yourself under the appropriate section. Use the same format as + the existing entries: handle, real name (if you want), one-line + contribution summary, link to PR(s). +3. If you want a snapshot update too, run the recipe in + [`docs/CONTRIBUTION_SNAPSHOT.md`](./CONTRIBUTION_SNAPSHOT.md) and + refresh the numbers in the same PR. + +This file is intentionally easy to contribute to — it's a doc, not a +tax form. Keep it warm. \ No newline at end of file