Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
451 lines (316 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

451 lines (316 loc) · 11.8 KB
Raw

Contributing to QA Studio

Thank you for your interest in contributing to QA Studio! We're excited to have you join our community of QA engineers building better testing tools.

Table of Contents

Code of Conduct

By participating in this project, you agree to maintain a respectful, inclusive, and collaborative environment. We welcome contributors of all skill levels and backgrounds.

Our values:

  • Be respectful and considerate
  • Focus on constructive feedback
  • Welcome newcomers and help them learn
  • Prioritize the community's needs over individual preferences

Getting Started

Ways to Contribute

You don't need to be a coding expert to contribute! Here are various ways to help:

  • 🐛 Report bugs - Found a bug? Open an issue
  • 💡 Suggest features - Have an idea? Start a discussion
  • 📝 Improve documentation - Help make our docs clearer
  • 🧪 Write tests - Add test coverage for existing features
  • 🔧 Fix bugs - Pick up a good first issue
  • ✨ Add features - Implement new functionality
  • 🎨 Improve UI/UX - Make the interface better
  • 💬 Help others - Answer questions on Discord or GitHub Discussions

Good First Issues

New to the project? Look for issues labeled good first issue. These are specifically chosen to be beginner-friendly.

How to Contribute

Reporting Bugs

Before reporting a bug:

  1. Check if it's already been reported in Issues
  2. Try to reproduce it with the latest version
  3. Gather relevant information (browser, OS, error messages, screenshots)

Create a bug report with:

  • Clear, descriptive title
  • Steps to reproduce the issue
  • Expected vs. actual behavior
  • Environment details (OS, browser, QA Studio version)
  • Screenshots or error logs if applicable

Suggesting Features

Feature requests are welcome! Before suggesting:

  1. Check existing discussions
  2. Consider if it aligns with QA Studio's core mission
  3. Think about how it benefits the broader community

Create a feature request with:

  • Problem statement (what problem does this solve?)
  • Proposed solution
  • Alternative solutions you've considered
  • How this helps other users

Asking Questions

Development Setup

Prerequisites

  • Node.js 18+ and npm
  • PostgreSQL 14+ or Docker
  • Git

Local Development

  1. Fork and clone the repository

    git clone https://github.com/YOUR_USERNAME/studio.git
cd studio

  2. Install dependencies

    npm install

  3. Set up environment variables

    cp .env.example .env.local

    Edit .env.local with your configuration:

    DATABASE_URL="postgresql://user:password@localhost:5432/qa_studio"
BLOB_READ_WRITE_TOKEN="your-vercel-blob-token"
ENCRYPTION_KEY="your-32-byte-hex-key"
CRON_SECRET="your-64-character-hex-string"

  4. Set up the database

    npx prisma generate
npx prisma db push

  5. Start the development server

    npm run dev

    Open http://localhost:5173

Using Docker (Alternative)

# Start PostgreSQL via Docker Compose
npm run docker:dev

# In another terminal, run the app
npm run dev

Pull Request Process

Before You Start

  1. Check for existing work - Search issues and PRs to avoid duplicates
  2. Discuss large changes - For significant features, open a discussion first
  3. Create an issue - For bugs or features, create an issue before coding

Creating a Pull Request

  1. Create a feature branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

  2. Make your changes

    • Follow our coding guidelines
    • Write tests for new functionality
    • Update documentation as needed
    • Keep commits focused and atomic

  3. Run checks before you commit

    CI runs the same gates on every pull request. Run these locally before git commit so you do not wait on a failed workflow:

    npm run format      # Apply Prettier (required — CI fails if files are unformatted)
npm run check       # Svelte/TypeScript typecheck (required for code changes)

    For broader validation (recommended when you change application logic):

    npm run lint        # Prettier check + ESLint
npm run test:unit -- --run   # Unit tests

    Important: npm run format rewrites files in place. Stage and include any formatting changes in your commit. The Format Check workflow runs npm run format and fails if git status is not clean afterward.

    If npm run check fails with missing $lib/paraglide/* modules, compile i18n first:

    npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide

  4. Commit your changes

    Use clear, descriptive commit messages:

    git commit -m "feat: add test case bulk import feature"
git commit -m "fix: resolve authentication redirect loop"
git commit -m "docs: update API documentation for test runs"

    Commit message format:

    • feat: New feature
    • fix: Bug fix
    • docs: Documentation changes
    • style: Code style changes (formatting, etc.)
    • refactor: Code refactoring
    • test: Adding or updating tests
    • chore: Maintenance tasks

  5. Push to your fork

    git push origin feature/your-feature-name

  6. Open a Pull Request

    • Use a clear, descriptive title
    • Reference related issues (e.g., "Fixes #123")
    • Describe what changed and why
    • Include screenshots for UI changes
    • Mark as draft if work is in progress

PR Review Process

  1. Automated checks - CI runs formatting (npm run format), type checking (npm run check), and tests — run these locally before pushing (see step 3 above)
  2. Code review - A maintainer will review your code
  3. Feedback - Address any requested changes
  4. Approval - Once approved, a maintainer will merge

Tips for faster reviews:

  • Keep PRs focused and small (easier to review)
  • Write clear descriptions
  • Respond promptly to feedback
  • Be patient - reviews may take a few days

Coding Guidelines

TypeScript

  • Use TypeScript for all code
  • Avoid any types - use proper typing
  • Export types from $lib/types.ts

Code Style

We use Prettier and ESLint for consistent formatting:

npm run format  # Format code
npm run lint    # Lint code

Key conventions:

  • Use tabs for indentation (project standard)
  • Use single quotes for strings
  • No semicolons (Prettier removes them)
  • Prefer const over let, avoid var
  • Use meaningful variable names

Svelte Components

  • Use Svelte 5 runes ($state, $derived, $effect)
  • Keep components focused and reusable
  • Use Skeleton UI components when possible
  • Follow existing component patterns

Example:

<script lang="ts">
	import { Button } from '@skeletonlabs/skeleton-svelte';

	let count = $state(0);
	let doubled = $derived(count * 2);
</script>

<Button onclick={() => count++}>
	Count: {count} (doubled: {doubled})
</Button>

Database

  • Use Prisma for all database operations
  • Write migrations for schema changes
  • Use transactions for multi-step operations
  • Follow import conventions (see CLAUDE.md)

Example:

import { db } from '$lib/server/db';
import { Prisma } from '$prisma/client';

const project = await db.project.create({
	data: {
		name: 'New Project',
		key: 'PROJ',
		createdBy: userId
	}
});

API Routes

  • Use requireAuth for protected endpoints
  • Validate inputs with Zod schemas (when using sveltekit-api)
  • Return proper HTTP status codes
  • Handle errors gracefully

Example:

import { requireAuth } from '$lib/server/auth';
import { json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const POST: RequestHandler = async (event) => {
	const userId = await requireAuth(event);

	const body = await event.request.json();

	// Validate, process, return
	return json({ success: true });
};

Testing

Running Tests

npm run test:unit      # Unit tests
npm run test:e2e       # End-to-end tests with Playwright
npm run test           # All tests

Writing Tests

Unit tests (Vitest):

import { describe, it, expect } from 'vitest';
import { generateId } from '$lib/server/ids';

describe('generateId', () => {
	it('should generate unique IDs', () => {
		const id1 = generateId();
		const id2 = generateId();
		expect(id1).not.toBe(id2);
	});
});

E2E tests (Playwright):

import { test, expect } from '@playwright/test';

test('user can create a project', async ({ page }) => {
	await page.goto('/projects/new');
	await page.fill('[name="name"]', 'Test Project');
	await page.fill('[name="key"]', 'TEST');
	await page.click('button[type="submit"]');

	await expect(page).toHaveURL(/\/projects\/TEST/);
});

Documentation

Types of Documentation

  • Code comments - Explain complex logic
  • README.md - Project overview and quick start
  • CLAUDE.md - Detailed architecture and conventions
  • API docs - Auto-generated from schemas
  • Blog posts - Feature announcements

Writing Good Documentation

  • Be clear and concise
  • Include code examples
  • Keep it up to date
  • Add screenshots for UI features
  • Link to related documentation

Updating Documentation

When you add or change features:

  • Update relevant documentation files
  • Add JSDoc comments for functions
  • Update API schemas in src/lib/api/schemas.ts
  • Consider writing a blog post for major features

Community

Communication Channels

  • GitHub Discussions - Feature requests, questions, ideas
  • GitHub Issues - Bug reports, concrete tasks
  • Discord - Real-time chat, community support
  • Blog - Feature announcements, tutorials

Getting Help

Stuck? Here's how to get help:

  1. Check documentation - README, CLAUDE.md, API docs
  2. Search existing issues - Someone may have had the same problem
  3. Ask on Discord - Community members can help
  4. Open a discussion - For open-ended questions

Recognition

Contributors are recognized in:

  • GitHub contributor graph
  • Release notes (for significant contributions)
  • Community shoutouts on Discord

License

By contributing to QA Studio, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means:

  • Your code will be open source
  • Anyone using it as a network service must share their modifications
  • Derivative works must use the same license

See the LICENSE file for full details.

Questions?

Have questions about contributing?

Thank you for contributing to QA Studio! 🎉