Contributing Guide

​

Welcome

​

Getting Started

1. Clone the repository to your local machine
2. Set up your development environment (see setup guide below)
3. Create a feature branch for your work
4. Make your changes following our guidelines
5. Submit a pull request when you’re ready

​

Development Setup

​

Prerequisites

​

Installation Steps

git clone https://github.com/deltahacks/portal.git
cd portal

pnpm install

cp .env.example .env

# Start the database using the provided script
./setup-db.sh

# Generate Prisma client and push schema
pnpm db:generate
pnpm db:push

pnpm dev

​

Project Structure

src/
├── app/                 # Next.js app directory (API routes)
├── assets/              # Static assets (pass files, images, etc.)
├── components/          # Reusable React components
├── data/               # Static data and constants
├── env/                # Environment variable schemas
├── pages/              # Next.js pages (legacy structure)
├── schemas/            # Zod schemas for validation
├── server/             # tRPC server-side code
│   ├── router/         # tRPC routers
│   ├── common/         # Shared server utilities
│   ├── db/             # Database-related code
│   └── trpc/           # tRPC configuration
│       └── router/     # Nested tRPC router structure
├── styles/             # Global styles
├── types/              # TypeScript type definitions
└── utils/              # Utility functions

​

Technology Stack

​

Code Organization

1. Components: Place reusable components in src/components/
2. Pages: Use the app directory for new pages, legacy pages are in src/pages/
3. API Routes: Place API routes in src/app/api/
4. Database: Use Prisma for all database operations
5. Validation: Use Zod schemas for input validation

​

Development Guidelines

​

Best Practices

​

Code Style

​

TypeScript

• Use strict TypeScript configuration
• Prefer interfaces over types for object shapes
• Use proper type annotations
• Avoid type assertions unless absolutely necessary

// Good
interface User {
  id: string;
  name: string;
  email: string;
}

function getUser(id: string): Promise<User> {
  // ...
}

// Avoid
function getUser(id: any): any {
  // ...
}

​

React

• Use functional components with hooks
• Follow React best practices
• Use proper prop types and interfaces
• Implement proper error boundaries

// Good
interface ButtonProps {
  onClick: () => void;
  children: React.ReactNode;
  disabled?: boolean;
}

function Button({ onClick, children, disabled = false }: ButtonProps) {
  return (
    <button onClick={onClick} disabled={disabled}>
      {children}
    </button>
  );
}

​

State Management Best Practices

// ❌ Bad - unnecessary state
const [fullName, setFullName] = useState(firstName + " " + lastName);

// ✅ Good - derived value
const fullName = firstName + " " + lastName;

// ❌ Bad - state for event handler only
const [isSubmitting, setIsSubmitting] = useState(false);
const handleSubmit = () => {
  setIsSubmitting(true);
  // ... submit logic
};

// ✅ Good - use ref or local variable
const isSubmittingRef = useRef(false);
const handleSubmit = () => {
  isSubmittingRef.current = true;
  // ... submit logic
};

// ❌ Bad - recalculating on every render
const expensiveValue = expensiveCalculation(data);

// ✅ Good - memoized calculation
const expensiveValue = useMemo(() => {
  return expensiveCalculation(data);
}, [data]);

// ❌ Bad - Effect for derived state
const [filteredTodos, setFilteredTodos] = useState([]);
useEffect(() => {
  setFilteredTodos(todos.filter((todo) => !todo.completed));
}, [todos]);

// ✅ Good - calculate during render
const filteredTodos = todos.filter((todo) => !todo.completed);

• If you can calculate something during render, you don’t need an Effect
• To cache expensive calculations, use useMemo instead of useEffect
• Code that runs because a component was displayed should be in Effects
• Code that runs because a user did something should be in event handlers

​

Styling

• Use TailwindCSS for styling
• Follow the existing design system
• Use CSS custom properties for theming
• Ensure responsive design

// Good - Tailwind classes
<button className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
  Click me
</button>

// Responsive design
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Content */}
</div>

​

File Naming

• Use PascalCase for components: MyComponent.tsx
• Use camelCase for utilities: myUtility.ts
• Use kebab-case for pages: my-page.tsx

​

Database Changes

​

Making Schema Changes

model User {
  id    String @id @default(cuid())
  name  String
  // Add new field
  phone String?
}

pnpm prisma migrate dev --name your_migration_name

pnpm prisma generate

pnpm db:push

​

Database Guidelines

• Always create migrations for schema changes
• Test migrations on a copy of production data when possible
• Document breaking changes in PR description
• Use proper relationships and constraints
• Consider migration rollback strategy

​

Pull Request Process

​

Before Submitting

​

Pull Request Guidelines

1. Use descriptive titles and descriptions
2. Reference related issues using keywords (Fixes #123, Closes #456)
3. Include screenshots for UI changes
4. Describe the changes and their impact
5. Request reviews from appropriate team members

​

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How to test these changes

## Screenshots (if applicable)
Add screenshots here

## Checklist
- [ ] Code follows style guidelines
- [ ] Tests pass
- [ ] Documentation updated

​

Commit Messages

feat: add new feature
fix: resolve bug
docs: update documentation
style: formatting changes
refactor: code restructuring
test: add or update tests
chore: maintenance tasks

feat(application): add dietary restrictions field to RSVP
fix(auth): resolve session expiration issue
refactor(judging): improve rubric scoring logic
docs: update contributing guide

​

Development Commands

# Development
pnpm dev              # Start development server (includes pnpm i && prisma generate)
pnpm build            # Build for production
pnpm start            # Start production server

# Code Quality
pnpm lint             # Run ESLint
pnpm format           # Format code with Prettier
pnpm format:check     # Check code formatting

# Database
pnpm db:generate      # Generate Prisma client and run migrations
pnpm db:migrate       # Deploy migrations to production
pnpm db:push          # Push schema to database
pnpm db:studio        # Open Prisma Studio

​

Testing

​

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

​

Writing Tests

import { describe, it, expect } from 'vitest';

describe('MyComponent', () => {
  it('renders correctly', () => {
    // Test implementation
    expect(true).toBe(true);
  });
});

​

Getting Help

​

Contact Channels

• Discord: Ask for help in the #technical-chat channel
• GitHub: Comment on pull requests or issues
• Email: tech@deltahacks.com

​

Technical VP Support Policy

​

When to Ask for Help Immediately

​

When to Spend More Time First

​

Before Reaching Out

1. Attempt to solve the problem yourself - Research, debug, try different approaches
2. Create a pull request - Show your attempted solution, even if it doesn’t work
3. Document your process - Explain what you tried, why it didn’t work, what you learned
4. Come prepared - Bring specific questions about what you’ve already attempted

​

How to Ask for Help Effectively

## Problem
Clear description of what you're trying to solve

## What I've Tried
1. First approach - why it didn't work
2. Second approach - what happened
3. Third approach - current state

## What I've Learned
Insights gained from debugging

## Specific Questions
- Where exactly am I stuck?
- What concept am I missing?

“I’m trying to add email notifications when an application is reviewed. I tried using SendGrid in the tRPC mutation, but emails aren’t sending. I checked: (1) API key is set, (2) email template exists, (3) no errors in logs. Here’s my PR: #123. Question: Should I be using a background job instead of sending inline?”

“Emails not working, can you help?”

​

Reporting Issues

​

Bug Reports

1. Clear description of the issue
2. Steps to reproduce
3. Expected vs actual behavior
4. Environment details (browser, OS, Node version)
5. Screenshots or videos if applicable
6. Error messages (full stack trace)

## Bug Description
Clear, concise description

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: [e.g. macOS 13.0]
- Browser: [e.g. Chrome 119]
- Node: [e.g. 18.17.0]

## Screenshots
Add screenshots here

## Error Messages

​

Feature Requests

1. Clear description of the feature
2. Use case and benefits
3. Implementation suggestions if any
4. Priority level (low, medium, high)

​

Resources

​

Documentation

• Next.js Docs
• TypeScript Handbook
• Prisma Docs
• tRPC Docs
• NextAuth.js Docs
• TailwindCSS Docs
• React Docs

​

Learning Resources

• T3 Stack Tutorial
• React Patterns
• TypeScript Deep Dive
• Prisma Tutorial

​

Code Review Guidelines

​

As a Reviewer

• Be constructive and respectful
• Explain why changes are needed
• Suggest alternatives when possible
• Approve when ready or request changes clearly
• Focus on:
  • Code correctness
  • Security implications
  • Performance concerns
  • Maintainability
  • Test coverage

​

As an Author

• Respond to all comments
• Ask questions if feedback is unclear
• Make requested changes or discuss alternatives
• Re-request review after addressing feedback
• Thank reviewers for their time

​

Additional Notes

​

Don’t Commit

• .env files
• node_modules/
• Build artifacts (dist/, .next/)
• IDE-specific files (.vscode/, .idea/)
• OS files (.DS_Store, Thumbs.db)
• Sensitive data or credentials

​

Do Commit

• Source code
• Configuration files (.env.example)
• Documentation
• Tests
• Database migrations
• Type definitions

• Architecture Overview
• Database Schema
• tRPC API
• Authentication