Skip to content

contributing-guide.mdx

Latest commit

 

History

History
196 lines (140 loc) · 7.32 KB

contributing-guide.mdx

File metadata and controls

196 lines (140 loc) · 7.32 KB
title Contributing to Chatwoot
description Complete guide to contributing to Chatwoot - from setting up your development environment to submitting pull requests.
sidebarTitle Introduction

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](https://github.com/chatwoot/chatwoot/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

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:

Complete setup guide for macOS developers Step-by-step Ubuntu installation guide Windows 10/11 development environment 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! 🚀