engineeringcommunication
Open Source Contributing Guide
Write open source contributing guides — with setup instructions, code standards, PR processes, issue templates, and community guidelines that lower the barrier for new contributors.
open-sourcecontributingcommunitypull-requestsguidelines
Works well with agents
Works well with skills
$ npx skills add The-AI-Directory-Company/(…) --skill open-source-contributing-guideopen-source-contributing-guide/
typescript-library.md
Markdown
| 1 | # Contributing to @fastform/core |
| 2 | |
| 3 | Thank you for your interest in contributing to fastform, a TypeScript form validation library. This guide covers everything you need to get started. |
| 4 | |
| 5 | ## Ways to Contribute |
| 6 | |
| 7 | - **Report bugs** — File an issue with a minimal reproduction |
| 8 | - **Fix bugs** — Issues labeled `good first issue` are a great starting point |
| 9 | - **Add features** — Open an issue to discuss before writing code |
| 10 | - **Improve docs** — Fix typos, add examples, clarify API descriptions |
| 11 | - **Write tests** — Increase coverage or add edge case tests |
| 12 | - **Review PRs** — Constructive feedback is always welcome |
| 13 | |
| 14 | Before starting, read our [Code of Conduct](CODE_OF_CONDUCT.md) and check [open issues](https://github.com/fastform/core/issues) to avoid duplicate work. |
| 15 | |
| 16 | ## Development Setup |
| 17 | |
| 18 | **Prerequisites**: Node.js 20+, pnpm 9+ |
| 19 | |
| 20 | ```bash |
| 21 | # 1. Fork and clone |
| 22 | git clone https://github.com/<your-username>/core.git |
| 23 | cd core |
| 24 | |
| 25 | # 2. Install dependencies |
| 26 | pnpm install |
| 27 | |
| 28 | # 3. Build the library |
| 29 | pnpm build |
| 30 | |
| 31 | # 4. Run the test suite to verify setup |
| 32 | pnpm test |
| 33 | ``` |
| 34 | |
| 35 | **Troubleshooting** |
| 36 | |
| 37 | | Error | Fix | |
| 38 | |-------|-----| |
| 39 | | `ERR_PNPM_NO_MATCHING_VERSION` | Ensure you are on Node 20+: `node -v` | |
| 40 | | `vitest: command not found` | Run `pnpm install` again — dev dependencies may not have installed | |
| 41 | | Type errors after pulling latest | Run `pnpm build` to regenerate type declarations | |
| 42 | |
| 43 | ## Code Standards |
| 44 | |
| 45 | ``` |
| 46 | Automated (CI enforces): |
| 47 | - Linting: ESLint — run `pnpm lint` locally |
| 48 | - Formatting: Prettier — run `pnpm format` to auto-fix |
| 49 | - Type checking: tsc --noEmit — run `pnpm typecheck` |
| 50 | - Tests: Vitest — run `pnpm test` |
| 51 | ``` |
| 52 | |
| 53 | **Commit messages** follow Conventional Commits: `<type>(<scope>): <description>` |
| 54 | |
| 55 | - `feat(validators): add minLength validator for arrays` |
| 56 | - `fix(core): handle undefined field values in nested schemas` |
| 57 | - `docs(readme): add usage example for async validation` |
| 58 | |
| 59 | ## Pull Request Process |
| 60 | |
| 61 | Before opening a PR: |
| 62 | - Branch is up to date with `main` |
| 63 | - All checks pass: `pnpm lint && pnpm typecheck && pnpm test` |
| 64 | - Tests added for new functionality |
| 65 | - API docs updated if public API changed (`docs/api.md`) |
| 66 | |
| 67 | **PR size guide**: Under 200 lines gets reviewed fastest. Over 500 lines — open an issue to discuss breaking it up. |
| 68 | |
| 69 | **Review process**: 1 maintainer approval required. CI must pass. Reviews happen within 5 business days. If you have not heard back after 5 days, comment on the PR to bump it. |
| 70 | |
| 71 | ## Issue Templates |
| 72 | |
| 73 | **Bug reports** must include: |
| 74 | - fastform version and Node.js version |
| 75 | - Minimal code snippet reproducing the issue |
| 76 | - Expected vs. actual behavior |
| 77 | - Error message or stack trace if applicable |
| 78 | |
| 79 | **Feature requests** must include: |
| 80 | - The problem you are trying to solve (not just the solution) |
| 81 | - A proposed API or usage example |
| 82 | - Alternatives you considered |
| 83 | |
| 84 | ## Issue Labels |
| 85 | |
| 86 | | Label | Meaning | |
| 87 | |-------|---------| |
| 88 | | `good first issue` | Scoped for new contributors, includes guidance in the description | |
| 89 | | `help wanted` | Maintainers welcome outside contributions on this | |
| 90 | | `bug` | Confirmed defect | |
| 91 | | `enhancement` | Approved feature request | |
| 92 | | `needs triage` | Not yet reviewed by a maintainer | |
| 93 | |
| 94 | ## Community |
| 95 | |
| 96 | - **GitHub Issues** — Bug reports, feature requests, and design discussions |
| 97 | - **GitHub Discussions** — Questions, ideas, and show-and-tell (response within 3 business days) |
| 98 | - **Discord** — `#fastform` channel for real-time help (best-effort, not guaranteed) |
| 99 | |
| 100 | Contributors are recognized in the release notes and on the [Contributors page](https://fastform.dev/contributors). |
| 101 |