Contributing to JobSync

March 4, 2026 · View on GitHub

Thank you for your interest in contributing to JobSync! This document outlines the process and guidelines for contributing to this project. Please read it carefully before submitting any contributions.

Contributing to JobSync

Code of Conduct

This project follows a Code of Conduct. By participating, you agree to uphold these standards. Please report unacceptable behavior to the project maintainers.

Getting Started

Prerequisites

Node.js 20+
npm
Git

Local Setup

Fork the repository on GitHub.

Clone your fork:

git clone https://github.com/<your-username>/jobsync.git
cd jobsync

Add the upstream remote:

git remote add upstream https://github.com/Gsync/jobsync.git

Install dependencies:
```
npm install
```
Copy the environment file and fill in your values:
```
cp .env.example .env
```
Set up the database:
```
npx prisma migrate dev
```
Start the development server:
```
npm run dev
```

How to Contribute

There are many ways to contribute:

Bug fixes — Find something broken? Fix it and open a PR.
Features — Check the open issues for ideas, or propose a new one first.
Documentation — Improve README, docs, or inline code comments.
Tests — Add missing unit or e2e tests.
Refactoring — Improve code quality without changing behavior.

For significant changes or new features, open an issue first to discuss your approach before writing code. This avoids duplicated effort and ensures alignment with the project's direction.

Development Workflow

Sync your fork with the latest dev branch before starting work:

git fetch upstream
git checkout dev
git merge upstream/dev

Create a focused branch from dev (see Branch Strategy):
```
git checkout -b feat/your-feature-name
```
Make your changes, keeping the scope narrow and focused.
Run lint and tests to verify everything passes (see Testing).
Commit your changes following the commit message conventions.
Push your branch to your fork and open a Pull Request.

Branch Strategy

Important: All pull requests must target the dev branch, never main. The main branch is the stable release branch and is only updated by maintainers via versioned merges from dev.

Naming Convention

Use one of these prefixes for your branch name:

Prefix	Purpose
`feat/`	New feature
`fix/`	Bug fix
`docs/`	Documentation only
`refactor/`	Code refactoring (no behavior change)
`test/`	Adding or improving tests
`chore/`	Build process, tooling, dependencies

Examples:

feat/add-resume-export
fix/automation-rate-limit
docs/update-api-routes
refactor/ai-provider-cleanup
test/task-actions-coverage

Commit Messages

Follow the Conventional Commits specification:

<type>(optional scope): <short summary>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat(automations): add rate limiting for manual runs
fix(tasks): prevent deletion of tasks with linked activities
docs: update environment variable list in README
refactor(ai): extract preprocessing into dedicated module
test(job-actions): add coverage for edge cases

Use the imperative mood in the summary ("add feature" not "added feature")
Keep the summary under 72 characters
Reference relevant issues in the footer: Closes #123

Pull Request Guidelines

Before Opening a PR

Ensure the following checks pass locally before submitting:

# Lint — must produce no errors
npm run lint

# Unit tests — all must pass
npm run test

# (Optional) E2e tests
npm run test:e2e

A PR that fails lint or tests will not be reviewed until those issues are resolved.

Keep PRs Small and Focused

Large PRs are difficult to review thoroughly and are more likely to introduce bugs. Follow these guidelines:

One concern per PR — a single bug fix, a single feature, or a single refactor; not all three.
Aim for under 400 lines changed (excluding generated files, migrations, and lock files).
If your change is large by necessity, break it into a sequence of smaller PRs that each build on the previous one.
Avoid bundling unrelated changes (e.g., fixing a bug while also reformatting unrelated files).

PR Checklist

Before submitting, verify:

Branch is based on dev, not main
npm run lint passes with no errors
npm run test passes with no failures
PR is scoped to a single concern
Changes are under ~400 lines (excluding generated/migration files)
PR description explains what and why
Relevant tests have been added or updated
Documentation is updated if behavior changes
npx prisma generate and a migration have been added for any schema changes

PR Description Template

When opening a PR, use this structure:

## Summary
A brief description of what this PR does and why.

## Changes
- List of specific changes made

## Related Issues
Closes #<issue-number>

## Testing
Describe how the change was tested.

Review Process

At least one maintainer approval is required to merge.
Address all review comments before requesting re-review.
Keep discussion respectful and constructive — see the Code of Conduct.
Maintainers may request changes, squash commits, or close a PR that no longer aligns with the project's goals.

Code Style

This project uses ESLint and TypeScript strict mode. All style rules are enforced via npm run lint.

Key conventions:

Imports: Use @/ absolute imports; group by external → internal → relative.
Naming: PascalCase for components, camelCase for functions/variables, kebab-case for files.
Types: All types live in src/models/*.model.ts; Zod schemas in src/models/*.schema.ts.
Server actions: Always validate auth with getCurrentUser() and return via handleError().
Database: Run npx prisma generate then npx prisma migrate dev after any schema change.
Files over 200 lines: Break into a directory with focused modules and a barrel index.ts.
Comments: Minimal; explain "why" not "what"; no decorative separator comments.

Testing

Unit Tests (Jest)

npm run test               # Run all unit tests
npm run test:watch         # Watch mode
npm run test -- path/to/test.test.ts   # Single file
npm run test -- --testNamePattern="test name"  # Single test

Tests live in __tests__/ and should be co-located where possible. Mock external dependencies (AI providers, database). Focus on server actions and component behavior.

E2E Tests (Playwright)

npm run test:e2e

E2E tests live in e2e/. These require a running dev server.

Reporting Bugs

Before filing a bug report, check if it has already been reported in the issue tracker.

When opening a bug report, include:

Description — clear summary of the problem.
Steps to reproduce — step-by-step instructions.
Expected vs. actual behavior.
Environment — OS, Node.js version, browser (if applicable).
Screenshots or logs — if relevant.

Suggesting Features

Open a feature request issue with:

Problem statement — what problem does this solve or what need does it address?
Proposed solution — your idea for how to implement it.
Alternatives considered — other approaches you thought of.

Feature requests are discussed before any implementation work begins.

Questions

If you have a question that isn't answered here, feel free to open a discussion or an issue tagged question.

Thank you for helping make JobSync better!