Contributing to BookWish

Welcome to the BookWish contributor guide! This section provides everything you need to know to contribute effectively to the project.

Getting Started

Before contributing, please:

1. Set up your development environment - Follow the Getting Started guide
2. Understand the architecture - Review the Architecture documentation
3. Read the coding standards - Familiarize yourself with our Code Style Guide
4. Check existing issues - Look for issues labeled "good first issue" or "help wanted"

Ways to Contribute

Code Contributions

• New features - Implement features from the roadmap or issues
• Bug fixes - Fix bugs reported in GitHub issues
• Performance improvements - Optimize code for better performance
• Tests - Add or improve test coverage
• Refactoring - Improve code quality and maintainability

Non-Code Contributions

• Documentation - Improve or expand documentation
• Bug reports - Report bugs with detailed reproduction steps
• Feature requests - Suggest new features or improvements
• Design feedback - Provide UI/UX feedback and suggestions
• Code review - Review pull requests from other contributors

Contribution Workflow

1. Find or Create an Issue

• Check the issue tracker for existing issues
• For new features or bugs, create an issue first to discuss the approach
• Get approval from maintainers before starting significant work

2. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR-USERNAME/bookwish_monorepo.git
cd bookwish_monorepo

# Add upstream remote
git remote add upstream https://github.com/your-org/bookwish_monorepo.git

3. Create a Branch

# Create a feature branch from main
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

4. Make Your Changes

Follow our coding standards:

• TypeScript/Node: No any types, no console logging, proper error handling
• Flutter/Dart: No print statements, no emoji in UI, use Cupertino icons
• General: Complete implementations, no TODOs in production code

See the Code Style Guide for detailed standards.

5. Test Your Changes

# Backend tests
cd backend
npm test
npm run lint

# Flutter tests
cd app
flutter test
flutter analyze

6. Commit Your Changes

Follow our commit message conventions:

# Good commit message
git commit -m "feat(wishlist): add export to CSV functionality"

# Bad commit message
git commit -m "updated files"  # Too vague

7. Push and Create Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Create a pull request on GitHub
# Follow the PR template and checklist

See the Pull Request Process for detailed guidelines.

Coding Standards

We maintain high coding standards to ensure code quality and consistency:

Required Standards

• No any type in TypeScript code
• No raw console logging - Use structured logging
• No TODO placeholders in production paths
• No drive-by refactors - Stay focused on the task
• No print statements in Flutter code
• No emoji in user-facing UI text
• Use Cupertino icons in Flutter (SF-style)
• Complete implementations - No partial work

See the Code Style Guide for complete standards.

Pull Request Guidelines

Before Submitting

• All tests pass
• Code follows style guide
• Linter passes with no errors
• Build succeeds
• Commit messages follow conventions
• Documentation is updated if needed

PR Requirements

• Clear title describing the change
• Description explaining what and why
• Link to related issues
• Screenshots for UI changes
• Testing notes

Review Process

• PRs are reviewed within 24-48 hours
• Address feedback within 24 hours
• All comments must be resolved before merge
• At least one approval required

See the Pull Request Process for details.

Commit Message Format

We use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

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

Examples:

feat(wishlist): add sharing functionality
fix(auth): resolve login redirect loop
docs(api): update authentication guide

See Commit Message Conventions for complete guidelines.

Documentation

Good documentation is essential:

• Code comments - Explain complex logic and non-obvious decisions
• API documentation - Document all public APIs and endpoints
• User documentation - Update user-facing docs for new features
• Architecture docs - Document significant architectural decisions

See Documentation Guidelines for standards.

Code of Conduct

Our Standards

• Be respectful - Treat all contributors with respect
• Be constructive - Provide helpful, actionable feedback
• Be collaborative - Work together to solve problems
• Be inclusive - Welcome contributors of all backgrounds and skill levels

Unacceptable Behavior

• Harassment, discrimination, or offensive comments
• Personal attacks or insults
• Publishing others' private information
• Trolling or deliberately disruptive behavior

Enforcement

Violations of the code of conduct should be reported to the project maintainers. All complaints will be reviewed and investigated promptly and fairly.

Getting Help

Resources

• Documentation - Start with the Developer Guide
• GitHub Issues - Search existing issues or create a new one
• Pull Requests - Review existing PRs for examples
• Architecture Docs - Understand the system design

Questions?

• Create an issue with the question label
• Tag relevant maintainers in your PR
• Check the FAQ if available

Recognition

We appreciate all contributions! Contributors are:

• Listed in the project's contributors file
• Mentioned in release notes for significant contributions
• Credited in documentation they help create

Quick Reference

Topic	Link
Code Style	Code Style Guide
Pull Requests	Pull Request Process
Commit Messages	Commit Conventions
Documentation	Documentation Guide
Architecture	Architecture Overview
Getting Started	Getting Started Guide
Tech Stack	Technology Stack

Next Steps

1. Set up your environment - Follow the Getting Started guide
2. Pick an issue - Find a "good first issue" to work on
3. Read the style guide - Review the Code Style Guide
4. Make your first contribution - Follow the workflow above

Thank you for contributing to BookWish! Together we're building a platform that supports independent bookstores and connects readers with the books they love.