Contributing Guidelines

Thank you for your interest in contributing to NPC Forge! This document provides guidelines and instructions for contributing to the project.

Getting Started

Setting Up the Development Environment

Fork the repository

Click the "Fork" button at the top right of the NPC Forge repository.

Clone your fork

git clone https://github.com/YOUR-USERNAME/npc-forge.git
cd npc-forge

Add the upstream remote

git remote add upstream https://github.com/EthanPerello/npc-forge.git

Install dependencies

Create a .env.local file

Start the development server

Development Workflow

Branching Strategy

We use a simplified GitFlow workflow:

• main: The main branch that always reflects production-ready code
• feature/name: Feature branches for new features and non-critical bugs
• fix/name: Fix branches for critical bug fixes

Working on a Feature or Bug Fix

Create a new branch from main

git checkout main
git pull upstream main
git checkout -b feature/your-feature-name
# or for fixes
git checkout -b fix/bug-description

Make your changes

Implement your feature or bug fix following the coding standards below.

Test your changes

• Test character generation and editing functionality
• Test chat features if your changes affect conversations
• Test portrait editing features if your changes affect image handling
• Test trait management features if your changes affect trait operations
• Verify library operations (save, load, filter, search)
• Test on both desktop and mobile interfaces
• Ensure dark mode compatibility

Commit your changes

Follow the commit message format:

git add .
git commit -m "feat: add character library feature"
# or for fixes
git commit -m "fix: resolve portrait generation error"

Commit Message Prefixes:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• style: for formatting changes
• refactor: for code refactoring
• test: for adding tests
• chore: for maintenance tasks

Keep your branch updated

git fetch upstream
git rebase upstream/main

Push your changes

Pull Request Process

Create a Pull Request

Go to the NPC Forge repository and click "New Pull Request".

Fill in the Pull Request template

Provide:

• A clear and concise description of your changes
• The issue number(s) your PR addresses (if applicable)
• Screenshots or examples if applicable
• Notes on testing performed
• Any breaking changes or dependencies

Update documentation

• Add your changes to the "Unreleased" section of CHANGELOG.md
• Update relevant documentation files if your changes affect user-facing features
• Include code comments for complex logic

Wait for review

A maintainer will review your PR and provide feedback. Make any requested changes by adding new commits to your branch.

Merge

Once approved, a maintainer will merge your PR.

Coding Standards

TypeScript

• Use TypeScript for all new code
• Define interfaces for all data structures
• Use explicit typing instead of any where possible
• Use optional chaining and nullish coalescing when appropriate
• Follow existing type definitions in src/lib/types.ts and src/lib/chat-types.ts

Component Development Guidelines

Wizard Interface Components:

• Follow the established step pattern in src/components/wizard-steps/
• Maintain consistent navigation and progress tracking
• Ensure responsive design across all steps
• Test with various character configurations

Chat System Components:

• Follow patterns established in chat page and context
• Ensure character consistency in AI responses
• Handle loading states and error conditions gracefully
• Test conversation flow and message persistence

Portrait Editing Components:

• Follow patterns established in portrait section component
• Ensure proper model compatibility validation
• Handle image processing states and error conditions
• Test with various edit prompts and image sizes
• Validate edit prompt input and provide appropriate feedback

Trait Management Components:

• Follow patterns established in additional traits section
• Ensure consistent trait display and formatting
• Handle AI generation states and error conditions
• Test trait addition, editing, and removal functionality
• Validate trait data and format appropriately

Character Library Components:

• Maintain IndexedDB integration patterns
• Follow the established component structure in src/components/edit-page/
• Ensure regeneration features work consistently
• Support the enhanced filtering system
• Test with large character collections

CSS/Styling

• Use Tailwind CSS for styling
• Follow the existing color scheme and design patterns
• Ensure responsive design works on mobile devices
• Use semantic HTML elements
• Test in both light and dark modes
• Maintain consistency with the established design system

Code Formatting

The project uses ESLint for code quality. Before submitting a PR:

Testing Guidelines

Manual Testing Requirements

Before submitting a PR, test the following areas:

Core Functionality:

• Character generation wizard (all four steps)
• Character library operations (save, load, edit, delete)
• Character regeneration features
• Import/export functionality

Chat System (if applicable):

• Starting conversations from character cards and library
• Message sending and receiving
• Character personality consistency
• Conversation persistence
• Model selection during chat

Portrait Editing System (if applicable):

• Portrait editing interface access and functionality
• Edit prompt input and validation
• Model compatibility checking
• Edit processing and result display
• Usage limit integration
• Error handling for various failure scenarios

Trait Management System (if applicable):

• Additional traits display and editing
• Custom trait addition and removal
• AI trait generation functionality
• Individual trait regeneration
• Trait formatting and validation
• Integration with existing trait display

User Interface:

• Responsive design on different screen sizes
• Dark mode functionality
• Navigation between pages
• Error handling and user feedback

Advanced Features:

• Enhanced filtering system with trait categories
• Search functionality with smart syntax
• Portrait generation and management
• Usage limit tracking and enforcement

Key Development Areas

Portrait Editing System

• Portrait editing interface improvements and optimization
• Edit prompt validation and processing enhancements
• Model compatibility and error handling improvements
• Integration with existing portrait management system
• Performance optimizations for image processing

Trait Management System

• Trait generation and regeneration improvements
• Trait display and formatting enhancements
• Custom trait management interface improvements
• Integration with existing character data structures

Chat System

• Conversation interface improvements
• Character personality consistency enhancements
• Message handling and storage optimizations
• Integration with character library features

UI/UX Improvements

• Responsive design enhancements
• Accessibility improvements and compliance
• Performance optimizations
• Dark mode refinements and consistency

API Integration

• New model support and integration
• Enhanced error handling and user feedback
• Usage tracking improvements and accuracy
• Rate limiting enhancements
• Portrait editing API optimization

Storage & Data

• IndexedDB optimizations and reliability
• Import/export enhancements
• Search and filtering performance improvements
• Data validation and error recovery

Feature Development Guidelines

Before Starting a Feature

1. 1Check Existing Issues: Search for related issues or feature requests
2. 2Discuss Approach: Comment on issues or create a discussion for major features
3. 3Review Architecture: Understand how your feature fits into the existing system
4. 4Plan Testing: Consider how you'll test your feature thoroughly

When Implementing Features

1. 1Follow Established Patterns: Use existing component and data flow patterns
2. 2Consider Edge Cases: Handle error conditions and unusual input
3. 3Maintain Consistency: Follow established UI patterns and terminology
4. 4Document Changes: Update relevant documentation files

Cost Considerations for Developers

API Usage During Development

When developing locally with your own OpenAI API key:

• Development mode bypasses usage limits but not OpenAI billing
• Use Standard tier models for most testing to minimize costs
• Test key features with Enhanced/Premium models sparingly
• Monitor your OpenAI usage dashboard regularly
• Set billing alerts in your OpenAI account

Testing Best Practices

• Use the minimum model tiers needed for testing
• Focus testing on logic and UI rather than extensive AI generation
• Create test characters once and reuse them
• Consider using mock data for extensive UI testing

Bug Reports

When submitting a bug report:

1. 1Use Clear Titles: Describe the issue concisely
2. 2Provide Steps to Reproduce: Include clear, numbered steps
3. 3Describe Expected Behavior: What should happen vs. what actually happens
4. 4Include Screenshots: Visual aids help diagnose UI issues
5. 5List Environment Details: Browser, OS, and relevant configuration
6. 6Check for Duplicates: Search existing issues first

Feature Requests

Before submitting a feature request:

1. 1Check Existing Issues: See if the feature has been requested
2. 2Review the Roadmap: Check if it's already planned
3. 3Consider Project Goals: Ensure alignment with project vision

When submitting a feature request:

1. 1Describe the Problem: What user need does this address?
2. 2Suggest a Solution: Provide implementation ideas if possible
3. 3Provide Examples: Include mockups or detailed descriptions
4. 4Indicate Willingness: State if you're willing to implement it

Documentation Contributions

We welcome documentation improvements:

• Fix Typos: Small corrections are always appreciated
• Improve Clarity: Make instructions clearer and more comprehensive
• Add Examples: Provide more examples and use cases
• Update Screenshots: Keep visual guides current with the interface
• Document New Features: Add documentation for portrait editing and trait management features
• Translate: Help make documentation accessible to more users

Communication

Code of Conduct

This project adheres to a code of conduct that ensures a welcoming environment for all contributors. By participating, you agree to:

• Be respectful and inclusive
• Focus on constructive feedback
• Help create a positive community
• Report any inappropriate behavior

Thank you for contributing to NPC Forge! Your efforts help make the project better for everyone.

Related Documentation

• Development Setup - Local environment configuration
• Architecture Overview - System design and components including new APIs
• Testing Guide - Comprehensive testing procedures including new features
• Security Documentation - Security considerations and practices