Contributing

Contributing

Thanks for your interest in Blinkql! Contributions of every size are welcome, and you don't need to write code to make a real difference.

Ways to contribute

	Contribution	How
🐛	Report bugs	Open an issue with steps to reproduce, your browser and, if possible, a small sample file (synthetic data only)
💡	Suggest features and use cases	Start a thread in Discussions
📊	Run benchmarks on your hardware	Follow Performance & Benchmarks and submit your results
🏭	Contribute sample datasets and templates	Share realistic synthetic datasets and analysis templates from your field: manufacturing, logistics, retail, finance, healthcare operations
🧑‍💻	Write code	Pick an issue labelled good first issue or help wanted
📝	Improve documentation	Fix unclear wiki pages, add examples, write tutorials
♿	Review accessibility	Test with a keyboard or screen reader and report what's hard to use
🎨	Design and UX	Propose improvements to flows, layouts and visual design

Never share real personal or confidential data in issues, discussions or pull requests. Use synthetic data that reproduces the shape of the problem.

Development setup

Prerequisites: Node.js 24 (the version in .nvmrc) and pnpm. Node's Corepack provides the exact pnpm version the project pins: run corepack enable pnpm once.

git clone https://github.com/Karthik-beta/Blinkql.git
cd Blinkql
pnpm install
pnpm dev          # start the dev server at http://localhost:5173

Useful scripts

pnpm typecheck    # TypeScript, strict mode
pnpm lint         # Biome lint rules
pnpm check        # Biome lint + formatting + import order (pnpm check:fix applies fixes)
pnpm test         # unit and integration tests (Vitest)
pnpm test:e2e     # end-to-end tests on Chromium, Firefox and WebKit (Playwright)
pnpm bench        # benchmark suite
pnpm build        # production build

Before the first pnpm test:e2e, download Playwright's browsers once with pnpm exec playwright install. End-to-end tests run against the production build (pnpm build + pnpm preview), which Playwright starts for you.

Workflow

1. Discuss first for big changes. For anything beyond a small fix, open an issue or discussion so effort isn't wasted.
2. Fork and branch from main: feat/csv-dialect-override, fix/grid-scroll-jump, perf/arrow-lazy-cells, docs/use-case-logs.
3. Commit with Conventional Commits, for example feat(editor): add schema-aware autocomplete or perf(grid): render rows from Arrow vectors. pnpm install sets up git hooks (Lefthook) that reject non-conventional messages and run biome check on staged files. PRs are squash-merged, so the PR title is checked the same way in CI.
4. Open a pull request and fill in the template.
5. CI must pass: typecheck, lint, tests, build and bundle-size check. main is protected: every change lands through a pull request, and the CI and PR-title checks must pass before it can merge.

Pull request checklist

• Tests added or updated for behaviour changes
• No new any without a comment explaining why
• Screenshots or a short recording for UI changes
• Performance-related changes include before/after benchmark numbers (see the write-up template)
• New interactive UI is keyboard-accessible and labelled
• Docs or wiki updated if behaviour changed

Issue labels

Label	Meaning
good first issue	Small, well-scoped, with guidance; ideal for a first contribution
help wanted	Contributions especially welcome
perf	Performance work; benchmark results expected
template	Analysis templates for the use-case packs
dataset	Sample or benchmark datasets
a11y	Accessibility
docs	Documentation and wiki
discussion	Needs design discussion before implementation

Proposing architectural changes

Changes that are hard to reverse (new core dependencies, data-flow changes, storage format changes) need an Architecture Decision Record. Start with a discussion, then add the ADR in your pull request.

Code of Conduct

Blinkql follows the Contributor Covenant. Be kind, assume good intent, and help make this a welcoming project for everyone.

License

Blinkql is MIT licensed. By contributing, you agree that your contributions are licensed under the same terms.

Recognition

Every contributor (code, docs, design, datasets, benchmarks or bug reports) is credited in the project README.