Skip to content
Contributing

Contributing

Contributions of every size are welcome — a typo fix is as valid as a new subsystem. This page is the short version; the canonical guide is CONTRIBUTING.md in the repository.

Before you start

  • Read the Code of Conduct. It applies to every space the project uses.
  • For anything larger than a bug fix, open an issue or a Discussion first so we can agree on the approach before you spend time on it.
  • Check the roadmap — your idea may already be planned, or deliberately not.

Development setup

You need Node.js 20 or newer and npm. No database, no API keys, no accounts.

git clone https://github.com/vectorlogic/vectorlogic.git
cd vectorlogic
npm ci
npm run dev      # http://localhost:3000

The site is a Next.js App Router project. Every page is a React Server Component by default; add "use client" only where interactivity genuinely requires it.

Coding standards

  • TypeScript, strict. No any without a comment explaining why.
  • Server Components first. Justify every client component in the pull request.
  • Conventions over cleverness. Follow the existing file layout and naming. New pages mirror the established page pattern: a Server Component with an exported metadata object.
  • Static content is data. Anything a non-engineer might edit lives in a data module, not hard-coded in a component.
  • Animations import from motion/react and must respect prefers-reduced-motion.
  • Accessibility is not optional. Semantic HTML, labelled controls, and visible focus states.

Before you open a pull request

npm run lint           # ESLint
npx tsc --noEmit       # Typecheck
npx next build         # Production build

All three must pass. A pull request that does not build, or that fails typecheck, will be asked to fix that first — it is not a style preference, it is the gate.

The pull request process

  1. Fork the repository and branch from the default branch.
  2. Keep one logical change per pull request. Small pull requests get reviewed faster and merge sooner.
  3. Write a description that says what changed and why. Link the issue it closes.
  4. Add or update tests where the change is testable. A bug fix should come with a regression test.
  5. Expect review comments. They are about the code, not about you. Address them or explain why not — either is fine.
  6. A maintainer merges once the change is approved and the checks are green. See governance for who reviews what.

Good first issues

We label approachable work good-first-issue. These are scoped so that you do not need deep familiarity with the codebase to finish one. Browse them at issues labelled good-first-issue. If you get stuck, say so on the issue — nobody is expected to figure it out alone.

Reporting bugs and security issues

Bugs go in the issue tracker. Security problems do not — report those privately following the security policy.

Documentation

Documentation fixes are among the most valuable contributions, because every future reader benefits. If something on this site or in the docs is wrong or unclear, that is a bug — please fix it.

By contributing, you agree that your contributions are licensed under the Apache License 2.0.