​
Contributing Guide

Thank you for taking an interest in contributing to Chatwoot! This guide will help you get started with contributing to our open-source customer support platform. Before submitting your contribution, please make sure to take a moment and read through the following guidelines.

​
Getting Started

Before starting your work, ensure an issue exists for it. If not, feel free to create one. You can also take a look into the issues tagged Good first issues.

​
Initial Steps

  1. Check for Existing Issues: Browse the GitHub issues to see if someone is already working on what you want to contribute.

  2. Comment on the Issue: Add a comment on the issue and wait for the issue to be assigned before you start working on it.

    • This helps to avoid multiple people working on similar issues.

  3. Propose Complex Solutions: If the solution is complex, propose the solution on the issue and wait for one of the core contributors to approve before going into the implementation.

    • This helps in shorter turn around times in merging PRs.

  4. Justify New Features: For new feature requests, provide a convincing reason to add this feature. Real-life business use-cases will be super helpful.

  5. Join the Community: Feel free to join our Discord community if you need further discussions with the core team.

​
Pull Request Guidelines

We use git-flow branching model. The base branch is develop. Please raise your PRs against the develop branch.

​
Before Submitting

  • Please make sure that you have read the issue triage guidelines before you make a contribution.
  • It’s okay and encouraged to have multiple small commits as you work on the PR - we will squash the commits before merging.
  • For other guidelines, see PR Guidelines
  • Ensure that all the text copies that you add into the product are i18n translatable. You are only required to add the English version of the strings. We pull in other language translations from our contributors on crowdin. See Translation guidelines to learn more.

​
Development Workflow

​
Developing a New Feature

# Create a branch in the following format:
feature/<issue-id>-<issue-name>

# Example:
feature/235-contact-panel

Requirements:

  • Add accompanying test cases
  • Follow our coding standards
  • Include proper documentation

​
Bug Fixes or Chores

# Branch naming for bug fixes:
fix/<issue-id>-<issue-name>

# Branch naming for chores:
chore/<description>

Requirements:

  • If you are resolving a particular issue, add fix: Fixes xxxx (#xxxx is the issue) in your PR title
  • Provide a detailed description of the bug in the PR
  • Add appropriate test coverage if applicable

​
Environment Setup

Choose the guide that matches your operating system:

macOS Setup

Complete setup guide for macOS developers

Ubuntu Setup

Step-by-step Ubuntu installation guide

Windows Setup

Windows 10/11 development environment setup

Docker Setup

Quick setup using Docker containers

​
Speed Up Development

Use our Make commands to speed up your local development workflow.

​
Project Setup

Once you have set up the environment, follow these guides to get Chatwoot running locally:

  1. Quick Setup Guide - Step-by-step setup instructions
  2. Environment Variables - Configuration options
  3. Common Errors - Troubleshooting guide

​
Special App Integrations

If you’re working on specific integrations:

​
Testing Your Contributions

We use comprehensive testing to ensure code quality:

​
Test Types

  • Unit Tests: Test individual components and functions
  • Integration Tests: Test component interactions
  • End-to-End Tests: Test complete user workflows with Cypress

​
Running Tests

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/models/user_spec.rb

# Run Cypress tests
npm run cypress:open

​
Documentation and Translation

​
Documentation Guidelines

  • Keep documentation clear and concise
  • Include code examples where helpful
  • Update documentation when changing functionality
  • Follow our translation guidelines

​
Internationalization

  • All user-facing text must be translatable
  • Only add English strings - other languages are handled via Crowdin
  • Use proper i18n keys and formatting

​
Community Guidelines

We strive to maintain a welcoming and inclusive community:

​
API Development

If you’re working on API-related features:

​
Recognition

We value all contributions to Chatwoot. Check out our Contributors page to see the amazing people who have helped make Chatwoot better.

​
Getting Help

Need assistance? Here are your options:

  • GitHub Issues: For bug reports and feature requests
  • Discord Community: For real-time discussions with the core team
  • Documentation: Comprehensive guides and API references
  • Community Forums: Connect with other contributors

Ready to start contributing? Pick an issue that interests you and follow our guidelines above. Every contribution, no matter how small, helps make Chatwoot better for everyone! 🚀