diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf0ecd9..393249f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -146,6 +146,129 @@ ARCHETYPES.set("mobile-engineer", { --- +## Contributing Without Code + +You don't need to write TypeScript to make a meaningful contribution. Most of +the work that makes this project useful — research, rules, anti-patterns, +sample CVs, translations, docs — comes from people with domain expertise, not +engineering skills. If you've ever reviewed a friend's CV, you've already done +80% of the work for several of these paths. + +### Five ways to contribute without coding + +#### 1. Add a research source + +Every scoring rule and keyword list should trace back to evidence — recruiter +interviews, hiring-manager surveys, market data. We currently cite 250+ +sources in [`research/sources.md`](research/sources.md). The bar to add one is +low and the impact is real. + +**How to do it:** +1. Find a credible source (recruiter post, hiring study, industry report). + Personal blogs and unsubstantiated opinions don't count — published or + institutional sources where possible. +2. Open an issue with the `research` label. Include: + - The source (URL + author + date) + - The specific claim it supports + - Which rule, archetype, or anti-pattern it backs +3. A maintainer will review and merge it into `research/sources.md` (or open a + PR if you'd like to do it yourself). + +**Example:** +> Source: "The 7 Things Recruiters Look For First" — John Smith, 2025. +> Supports: `keywordMatch` rubric dimension. +> Specific claim: "80% of recruiters spend less than 6 seconds on initial scan; +> keyword presence is the dominant factor in pass/fail." + +**Time cost:** 10–20 minutes per source. + +#### 2. Propose an anti-pattern + +Every archetype ships with an `antiPatterns` list — phrases like *"passionate +about products"*, *"leveraged synergies"*, *"team player"*, *"familiar with X"* +that read as filler to recruiters. These come from real CVs and real recruiter +feedback, not from a textbook. If you've spotted one in the wild, add it. + +**How to do it:** +1. Find a phrase in your own CV (or a friend's) that you now realize was filler. +2. Check [`packages/core/src/archetypes/`](packages/core/src/archetypes/) — if + it's not already listed for the relevant archetype, open an issue with the + `rules` label. +3. Include: + - The phrase + - Which archetype it's relevant to (or "all") + - Why it reads as filler (1–2 sentences) + +**Time cost:** 5–10 minutes per anti-pattern. + +#### 3. Provide a sample CV (or job description) + +We don't have public test fixtures. That means contributors writing scoring +rules have nothing to test against, and users have nothing to compare their +own CV to. A small library of sample CVs — deliberately imperfect, with weak +metrics, vague impact, missing quantification — would unlock both contributor +testing and user demos. + +**How to do it:** +1. Author a fictional CV: 1 page, 3–5 years of experience, deliberately + include 2–3 weak spots. Or anonymize your own. +2. Pair it with a fictional job description. +3. Open an issue with the `examples` label and attach both files (or paste + inline). +4. Maintainers will add to `examples/` (we'll create the directory). + +**Time cost:** 30–45 minutes per pair. + +#### 4. Improve the docs + +Docs gaps are everywhere. The `docs/` directory has architecture notes, a +phase-1 plan, and an issues seed — but no contributor onboarding doc, no +"frequently asked questions," no "I just got a bad score, what do I do" +guide, no CLI troubleshooting, no glossary of evaluation terms. Each of +these is a 1-page writeup. + +**How to do it:** +1. Pick a gap from the list above (or one you've personally hit). +2. Write the doc in `docs/`. +3. Open a PR using the branch naming `docs/`. + +**Time cost:** 30–90 minutes per doc. + +#### 5. Triage issues and help others + +The fastest way to become a recognized contributor is to be the person who +answers questions. Right now most issues get one response from a maintainer +— if you can answer even one open issue, you free maintainer time and signal +"I'm here, I know this codebase." + +**How to do it:** +1. Look at issues with the `help wanted` or `good first issue` label. +2. If you can answer a question (even partially), comment. If you can reproduce + a bug, comment with the steps. +3. If you're confident a label is missing or an issue is a duplicate, suggest + it via a comment (maintainers will adjust labels). + +**Time cost:** 5–15 minutes per issue. + +--- + +### How to submit a non-code contribution + +The workflow is the same as code, minus the obvious steps: + +1. **Open an issue first** using the most relevant label (`research`, `rules`, + `examples`, `docs`). Comment "I'll take this" to claim it. +2. **For docs / examples:** fork → branch → PR. Branch-naming + conventions from the [Development Workflow](#development-workflow) section + still apply (`docs/`, `archetype/`, etc.). +3. **For research / anti-patterns / triage:** an issue is enough — no PR + needed unless you want to write the change yourself. + +A maintainer will respond within 48 hours. If you don't hear back, ping the +[Telegram group](https://t.me/techimmigrants). + +--- + ## Guidelines - **One issue = one PR.** Don't bundle unrelated changes. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..b872096 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,93 @@ +# Roadmap + +This file tracks **what we're actively working on right now** and **what's +open for grabs**. For the **vision** (v0.1, v0.2, v0.3), see the +[README Roadmap section](README.md#roadmap). This file is the **current state** +— what maintainers and contributors are doing this week and next. + +## How to read this + +- 🚧 **In progress** — assigned, being worked on, has an ETA. Don't pick up + unless you coordinate with the assignee. +- 🎯 **Up next** — open for grabs. Comment "I'll take this" on the linked + issue to claim it. Every item here is sized for one PR. +- 🅿️ **Parked** — explicitly deprioritized for now. Pick up only after + discussion with a maintainer. + +**If you're a new contributor, start in 🎯 Up next.** Every item there has +an acceptance bar reachable in a single sitting (1–4 hours). + +--- + +## 🚧 In progress + +| Item | Owner | ETA | Notes | +|---|---|---|---| +| **Merge Phase-1 stack** — PRs [#68](https://github.com/TechImmigrants/cv-builder/pull/68), [#69](https://github.com/TechImmigrants/cv-builder/pull/69), [#70](https://github.com/TechImmigrants/cv-builder/pull/70), [#71](https://github.com/TechImmigrants/cv-builder/pull/71), [#72](https://github.com/TechImmigrants/cv-builder/pull/72), [#73](https://github.com/TechImmigrants/cv-builder/pull/73) | @saharpak | **ASAP** | Open since 2026-06-07. Currently the single biggest contributor-experience blocker — new contributors cloning `main` get a different product than what's documented. **Reviewer help urgently wanted — see below.** | +| CV/JD input screen with file upload — PR [#76](https://github.com/TechImmigrants/cv-builder/pull/76) | unassigned | TBD | Two-column input screen. Depends on Phase-1 merge. | +| CodeRabbit config expansion — PR [#75](https://github.com/TechImmigrants/cv-builder/pull/75) | unassigned | TBD | Per-package review guidance. | +| Rule: flag outdated technologies — PR [#74](https://github.com/TechImmigrants/cv-builder/pull/74) | unassigned | TBD | Resolves issue [#53](https://github.com/TechImmigrants/cv-builder/issues/53). | +| CI: web UI deploy previews on Cloudflare Pages — PR [#78](https://github.com/TechImmigrants/cv-builder/pull/78) | unassigned | TBD | Path-filtered workflow. | + +> ### ⚠️ Reviewer help wanted on Phase-1 PRs +> +> The bottleneck isn't writing code — it's review bandwidth. If you have +> **TypeScript + zod** experience and can review one of #68–#73, comment on +> the PR. A 30-minute review from someone other than the maintainer unblocks +> the entire stack and signals to the rest of the contributor base that the +> project is moving. + +--- + +## 🎯 Up next — open for grabs + +These have linked issues, explicit acceptance criteria, and a one-PR-sized +scope. **Comment "I'll take this" on the issue to claim.** + +| Item | Effort | Issue | Notes | +|---|---|---|---| +| Add integration test for full evaluation pipeline | M (2–4 h) | [#51](https://github.com/TechImmigrants/cv-builder/issues/51) | `help wanted`, `core`. End-to-end test of `evaluate()`. | +| Add GitHub Actions workflow for lint + tests | S (1–2 h) | [#46](https://github.com/TechImmigrants/cv-builder/issues/46) | `help wanted`, `core`. May already partially exist — check `.github/workflows/` first. | +| Convert `types.ts` to Zod schemas | M | [#47](https://github.com/TechImmigrants/cv-builder/issues/47) | `enhancement`, `core`. | +| Add example test CVs for local development | S (30–60 min) | [#50](https://github.com/TechImmigrants/cv-builder/issues/50) | `good first issue`. Author 2–3 fictional CVs + 1 JD. | +| Rule: flag generic summary / objective section | S | [#45](https://github.com/TechImmigrants/cv-builder/issues/45) | `good first issue`, `rules`. | +| Rule: detect missing action verbs in bullet points | S | [#52](https://github.com/TechImmigrants/cv-builder/issues/52) | `good first issue`, `rules`. | +| Rule: flag outdated technologies | S | [#53](https://github.com/TechImmigrants/cv-builder/issues/53) | `good first issue`, `rules`. **PR #74 already in flight — check before starting.** | +| Add per-dimension feedback strings to evaluator | S | [#48](https://github.com/TechImmigrants/cv-builder/issues/48) | `enhancement`, `core`. | +| Fix: flag missing contact information | S | [#55](https://github.com/TechImmigrants/cv-builder/pull/55) | `core`. PR already open — needs review. | +| New archetype: **AI Engineer** | M | (open issue) | Use the [New Archetype template](.github/ISSUE_TEMPLATE/new_archetype.md). Top priority for the 2026 market. | +| New archetype: **AI Product Manager** | M | (open issue) | Top priority for the 2026 market. | +| New archetypes: Backend / Frontend / DevOps | M each | (open issue) | Currently advertised in README but unimplemented. | +| Land CONTRIBUTING.md "no-code" section | S | (open issue) | The draft this file came from. | +| Write `docs/faq.md` ("I got a bad score, what now?") | S | (open issue) | | +| Write `docs/cli-troubleshooting.md` | S | (open issue) | | +| Write `docs/evaluation-glossary.md` | S | (open issue) | | + +--- + +## 🅿️ Parked + +| Item | Why parked | When to revisit | +|---|---|---| +| PDF export | Real effort; needs design decisions (template engine, fonts, ATS-safe output). | After Phase-1 merge + web UI MVP. | +| VS Code / Cursor extension | Significant scope; needs stable core API first. | After PDF export and at least 8 archetypes shipped. | +| Self-hosted deployment guide | Requires production stability first. | After v0.2 lands. | +| LLM-enhanced mode (rewrite suggestions) | Cost implications and prompt-design work. | After core scoring is stable. | +| Side-by-side tailoring editor | Needs mature web UI. | After web UI MVP ships. | +| Localization (multiple languages) — beyond README | Translation tooling, RTL support, glossary. | After first 3 README translations land. | +| Before/after examples library | Needs curation and editorial review. | After core scoring is stable. | + +--- + +## How to influence this roadmap + +- **Pick up an item from 🎯 Up next** — comment "I'll take this" on the issue. +- **Suggest new items** — open an issue with the relevant label. +- **Push a 🅿️ Parked item** — if you think something should be un-parked, + open an issue with the `roadmap` label and the rationale. +- **Help review Phase-1 PRs** — the single highest-leverage thing a + TypeScript-comfortable contributor can do this week. + +--- + +*Last updated: 2026-06-22*