Contributing

Guidelines for contributing to ZeroStarter

Overview

We welcome contributions to ZeroStarter! This guide outlines the process for contributing code, documentation, and other improvements to the project. Following these guidelines helps ensure a smooth review process and maintains code quality.

By contributing, you agree to the MIT license and the project’s Code of Conduct.

Quick Start

Ready to contribute? Here’s the fastest path:

1. Fork and clone

   Fork the ZeroStarter repository and clone it locally:

   git clone https://github.com/YOUR_USERNAME/zerostarter.git
   cd zerostarter
   
2. Install dependencies

   bun install
   
3. Create a branch

   Use descriptive branch names following the convention:

   git checkout -b feat/your-feature-name
   # or
   git checkout -b fix/issue-description
   
4. Make your changes

   Write code, add tests if applicable, and ensure all checks pass (see below).

5. Submit a pull request

   Push your changes and open a PR with a clear description.

Branch Naming Convention

Use descriptive branch names that indicate the type and purpose of your changes:

Type	Example	Use for
feat/	feat/stripe-integration	New features
fix/	fix/auth-redirect-loop	Bug fixes
docs/	docs/update-readme	Documentation updates
refactor/	refactor/api-error-handling	Code refactoring
test/	test/add-auth-tests	Adding tests
chore/	chore/update-dependencies	Maintenance tasks

Good branch names: feat/resend-email, fix/database-migration, docs/installation-guide

Development Workflow

1. Set up your development environment

Follow the Installation guide to set up ZeroStarter locally:

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Set up database
bun run db:generate
bun run db:migrate

# Start development server
bun dev

2. Make your changes

Write clean, well-documented code following the existing code style.

Do not comment unnecessarily. Only add comments if absolutely necessary. The code should be self-documenting.

Code style guidelines:

• Use TypeScript for all new code
• Use @/ for imports where applicable
• Follow existing patterns in the codebase
• Keep functions small and focused
• Use descriptive variable and function names

3. Run quality checks

Before submitting your PR, ensure all checks pass:

# Build all packages
bun run build

# Type checking
bun run check-types

# Format code
bun run format

# Lint code
bun run lint

All of these checks must pass for your PR to be merged. Fix any errors before submitting.

4. Test your changes

While ZeroStarter doesn’t currently have automated tests, you should:

1. Manually test your changes thoroughly
2. Test in both development and production builds:
   bun run build
   bun run start
   
3. Test edge cases and error scenarios
4. Verify existing functionality still works

If you’re adding a new feature, consider adding tests. Contributions that include tests are highly valued!

5. Commit your changes

Use Conventional Commits format:

git commit -m "feat: add Stripe payment integration"
git commit -m "fix: resolve OAuth redirect loop"
git commit -m "docs: update installation guide"
git commit -m "refactor: simplify API error handling"

Commit message format:

<type>: <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring (no functionality change)
• test: Adding or updating tests
• chore: Maintenance tasks (dependencies, configs, etc.)
• perf: Performance improvements
• style: Code style changes (formatting, not CSS)

Examples:

feat: add email verification with Resend

fix: prevent double form submission on auth pages

docs: add troubleshooting section for database issues

refactor: extract validation schemas to separate files

Lefthook is configured to run commitlint on commit messages. Invalid commit messages will be rejected.

Pull Request Guidelines

Before submitting

• ✅ All quality checks pass (build, check-types, format, lint)
• ✅ Changes are tested manually
• ✅ Commit messages follow conventional commits
• ✅ Branch is up to date with main or canary
• ✅ No unnecessary files committed (build artifacts, .env, etc.)

PR description template

Provide a clear description of your changes:

## Description

Brief summary of what this PR does.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Changes made

- List specific changes
- Include relevant details
- Explain decisions if needed

## Testing

How did you test this? What scenarios did you cover?

## Related issues

Closes #123
Related to #456

## Migration notes

Any breaking changes or migration steps required?

## Screenshots (if applicable)

Add screenshots for UI changes.

Review process

1. Automated checks run on your PR (type checking, linting)
2. Maintainer review - we’ll review your code and provide feedback
3. Address feedback - make requested changes
4. Approval and merge - once approved, your PR will be merged

PRs are usually reviewed within 1-3 days. Larger changes may take longer.

Types of Contributions

Bug Fixes

Found a bug?

1. Check if an issue already exists
2. Open a new issue if needed
3. Create a PR with the fix
4. Link the issue in your PR description

Bug fix checklist:

• Identify the root cause
• Write a fix that addresses the cause
• Verify the fix doesn’t break other functionality
• Test edge cases
• Document the fix in the commit message

New Features

For large features or breaking changes, open an issue first to discuss the approach. This prevents wasted effort if the feature doesn’t align with project goals.

Feature contribution checklist:

• Open an issue to discuss the feature
• Get approval from maintainers
• Implement the feature following existing patterns
• Update documentation
• Add examples if applicable
• Ensure backward compatibility (or document breaking changes)

Documentation

Documentation improvements are always welcome!

Documentation contributions:

• Fix typos or unclear explanations
• Add missing documentation
• Improve examples
• Add troubleshooting guides
• Translate documentation (if supported)

Documentation is located in:

• README.md - Project overview
• web/next/content/docs/ - Full documentation (if using Fumadocs)

Integrations

Planning to add an integration from the roadmap?

1. Check the roadmap

   See the roadmap for planned integrations and their priority.

2. Open an issue

   Discuss your implementation approach before starting work.

3. Follow the pattern

   Look at existing integrations (Better Auth, PostHog) for patterns to follow.

4. Make it optional

   Integrations should be optional and configurable via environment variables.

5. Document it

   Add documentation explaining how to set up and use the integration.

Code Review Guidelines

When reviewing others’ contributions:

Focus on substance

• Is the code correct and bug-free?
• Does it follow existing patterns?
• Is it well-structured and maintainable?
• Are there edge cases to consider?

Be constructive

• Explain why something should change
• Suggest alternatives
• Acknowledge good work
• Be respectful and professional

Test the changes

• Pull the branch and test locally
• Verify the changes work as described
• Check for unintended side effects

Getting Help

Need help contributing?

Ask in Issues

Open an issue with your question.

Check Documentation

Review the full documentation.

FAQ

Check frequently asked questions.

Follow Updates

Follow @nrjdalal for updates.

Code of Conduct

Our Standards

We are committed to providing a welcoming and inclusive environment:

• Be respectful - Value differing opinions and experiences
• Be collaborative - Work together toward the best solution
• Be professional - Keep discussions focused and constructive
• Be open - Welcome newcomers and help them learn

Unacceptable Behavior

• Harassment or discriminatory language
• Personal attacks or insults
• Trolling or inflammatory comments
• Publishing others’ private information
• Other conduct inappropriate in a professional setting

Violations of the Code of Conduct may result in removal from the project.

License

By contributing to ZeroStarter, you agree that your contributions will be licensed under the MIT License.

This means:

• Your code can be used freely by anyone
• No warranty or liability
• Attribution to original authors is preserved

Recognition

All contributors are recognized in the repository:

Amazing Contributors

See all contributors who have helped build ZeroStarter.

Your GitHub profile will be displayed on the README once your PR is merged!

Thank You!

Thank you for contributing to ZeroStarter! Every contribution, no matter how small, helps make the project better for everyone.

Questions about contributing? Open an issue and we’ll help you get started!