Contributing¶

Thank you for your interest in contributing to Stowaway! This guide will help you get started.

Getting Started¶

1. Fork the Repository¶

Click the "Fork" button on GitHub to create your own copy.

2. Clone Your Fork¶

git clone https://github.com/yourusername/stowaway.git
cd stowaway

3. Create a Branch¶

git checkout -b feature/your-feature-name

4. Set Up Development Environment¶

# Install dependencies
npm install

# Set up environment
cp .env.example .env

# Run database migrations
npx prisma migrate dev

# Start development server
npm run dev

Development Workflow¶

Code Style¶

• We use ESLint for code linting
• Run npm run lint before committing
• Follow existing code patterns
• Use TypeScript strict mode

Commit Messages¶

Use clear, descriptive commit messages following Conventional Commits:

feat: add barcode scanning feature
fix: resolve login redirect issue
docs: update API documentation
style: format code with prettier
refactor: simplify authentication logic
test: add unit tests for item API

Pull Request Process¶

1. Update documentation if needed
2. Run tests: npm test
3. Run linter: npm run lint
4. Ensure build passes: npm run build
5. Create a pull request with a clear description

Project Structure¶

stowaway/
├── docs/                # Documentation (MkDocs)
├── prisma/              # Database schema & migrations
├── public/              # Static assets
├── src/
│   ├── app/
│   │   ├── (auth)/     # Authentication pages
│   │   ├── (dashboard)/ # Main application
│   │   └── api/        # REST API routes
│   ├── components/
│   │   ├── ui/         # shadcn/ui components
│   │   └── [feature]/  # Feature components
│   └── lib/            # Utilities
└── uploads/            # User uploads

Adding Features¶

New API Endpoint¶

1. Create route in src/app/api/[endpoint]/route.ts
2. Add Zod schema in src/lib/validations.ts
3. Use auth() for session validation
4. Update SPECIFICATION.md
5. Add API documentation

New Page¶

1. Create page in src/app/(dashboard)/[page]/page.tsx
2. Add navigation link in src/components/layout/sidebar.tsx
3. Create required components

Database Changes¶

1. Update prisma/schema.prisma
2. Run npx prisma migrate dev --name description
3. Update related routes and components
4. Update documentation

Testing¶

# Run unit tests
npm test

# Run E2E tests
npm run test:e2e

# Run with coverage
npm run test:coverage

Documentation¶

Documentation is built with MkDocs and hosted on GitHub Pages.

Local Preview¶

# Install Python dependencies
pip install -r requirements.txt

# Serve documentation locally
mkdocs serve

# Open http://localhost:8000

Building Docs¶

mkdocs build

Questions?¶

• Open an issue for questions or discussion
• Join discussions on GitHub

Code of Conduct¶

Be respectful and inclusive. We follow the Contributor Covenant.