akadmin/chatwoot
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

add intro documentation and user guide

Browse Source
This commit is contained in:
Tanmay Deep Sharma
2025-05-29 19:29:32 +05:30
parent f429db89b4
commit 7808634432
203 changed files with 8020 additions and 7794 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-docs/contributing/introduction.mdx
+137 -263
View File
@@ -4,319 +4,193 @@ description: Complete guide to contributing to Chatwoot - from setting up your d
sidebarTitle: Introduction
---
Thank you for your interest in contributing to Chatwoot! This guide will help you get started with contributing to our open-source customer support platform. Whether you're fixing bugs, adding features, or improving documentation, your contributions are valuable to the community.
# Contributing Guide
## Why Contribute to Chatwoot?
Contributing to Chatwoot offers many benefits:
- **Learn and Grow**: Work with modern technologies like Ruby on Rails, Vue.js, and PostgreSQL
- **Make an Impact**: Help thousands of businesses improve their customer support
- **Build Your Portfolio**: Showcase your contributions to a popular open-source project
- **Join the Community**: Connect with developers and users from around the world
- **Give Back**: Support the open-source ecosystem
## Ways to Contribute
There are many ways to contribute to Chatwoot:
### 🐛 Bug Reports and Fixes
- Report bugs you encounter
- Fix existing bugs in the codebase
- Improve error handling and edge cases
### ✨ Feature Development
- Implement new features
- Enhance existing functionality
- Improve user experience
### 📚 Documentation
- Improve existing documentation
- Write new guides and tutorials
- Translate documentation to other languages
### 🧪 Testing
- Write unit and integration tests
- Perform manual testing
- Improve test coverage
### 🎨 Design and UX
- Improve user interface design
- Enhance user experience
- Create mockups and prototypes
### 🌍 Localization
- Translate Chatwoot to new languages
- Improve existing translations
- Help with internationalization
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
### Prerequisites
<Warning>
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).
</Warning>
Before you start contributing, make sure you have:
### Initial Steps
- **Git**: Version control system
- **GitHub Account**: For submitting pull requests
- **Development Environment**: See our environment setup guides
- **Basic Knowledge**: Familiarity with Ruby, JavaScript, or the technology you want to work with
1. **Check for Existing Issues**: Browse the [GitHub issues](https://github.com/chatwoot/chatwoot/issues) to see if someone is already working on what you want to contribute.
### Development Workflow
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.
Our development workflow follows these steps:
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.
1. **Find an Issue**: Look for issues tagged with "Good first issue" or create a new one
2. **Fork the Repository**: Create your own copy of the Chatwoot repository
3. **Create a Branch**: Make a feature branch for your changes
4. **Make Changes**: Implement your fix or feature
5. **Test Your Changes**: Ensure everything works correctly
6. **Submit a Pull Request**: Open a PR with a clear description
7. **Code Review**: Collaborate with maintainers to refine your changes
8. **Merge**: Your contribution becomes part of Chatwoot!
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.
## Before You Start
### 1. Check Existing Issues
Before starting work, check if someone else is already working on the same issue:
- Browse [open issues](https://github.com/chatwoot/chatwoot/issues)
- Look for issues labeled "Good first issue" for beginners
- Check if there's an existing pull request for the same feature
### 2. Create or Comment on an Issue
- **For new features**: Create an issue to discuss the feature before implementing
- **For existing issues**: Comment that you'd like to work on it
- **Wait for assignment**: This helps avoid duplicate work
### 3. Understand the Codebase
Familiarize yourself with:
- **Architecture**: How Chatwoot is structured
- **Coding Standards**: Our style guides and conventions
- **Testing Practices**: How we write and run tests
5. **Join the Community**: Feel free to join our [Discord community](https://discord.com/invite/cJXdrwS) if you need further discussions with the core team.
## Pull Request Guidelines
### Branch Naming
<Info>
We use git-flow branching model. The base branch is `develop`. Please raise your PRs against the `develop` branch.
</Info>
Use descriptive branch names that follow our conventions:
### Before Submitting
- Please make sure that you have read the [issue triage guidelines](https://www.chatwoot.com/hc/handbook/articles/issue-triage-29) 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](https://www.chatwoot.com/hc/handbook/articles/pull-request-guidelines-32)
- 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](https://www.chatwoot.com/docs/contributing-guide/translation-guidelines) to learn more.
## Development Workflow
### Developing a New Feature
```bash
# Feature branches
feature/issue-id-short-description
# Create a branch in the following format:
feature/<issue-id>-<issue-name>
# Example:
feature/235-contact-panel
# Bug fix branches
fix/issue-id-short-description
fix/123-email-validation
# Chore branches
chore/update-dependencies
chore/improve-documentation
```
### Commit Messages
**Requirements:**
- Add accompanying test cases
- Follow our coding standards
- Include proper documentation
Write clear, descriptive commit messages:
### Bug Fixes or Chores
```bash
# Good commit messages
feat: Add contact search functionality (#235)
fix: Resolve email validation issue (#123)
docs: Update installation guide
test: Add unit tests for contact model
# Branch naming for bug fixes:
fix/<issue-id>-<issue-name>
# Avoid
Update stuff
Fix bug
WIP
# Branch naming for chores:
chore/<description>
```
### Pull Request Template
**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
When creating a pull request, include:
## Environment Setup
**Description:**
- Clear description of what the PR does
- Link to related issues
- Screenshots for UI changes
**Testing:**
- How you tested the changes
- Test cases covered
- Any manual testing performed
**Checklist:**
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or clearly documented)
### Example Pull Request
```markdown
## Description
Adds a new contact search feature that allows agents to quickly find contacts by name, email, or phone number.
Fixes #235
## Changes Made
- Added search input to contact panel
- Implemented backend search API
- Added debounced search functionality
- Updated contact list component
## Testing
- Added unit tests for search API
- Tested search with various input types
- Verified performance with large contact lists
- Manual testing on different browsers
## Screenshots
[Include screenshots of the new feature]
## Checklist
- [x] Code follows style guidelines
- [x] Self-review completed
- [x] Tests added
- [x] Documentation updated
- [x] No breaking changes
```
## Code Standards
### Ruby/Rails Standards
- Follow [Ruby Style Guide](https://rubystyle.guide/)
- Use [RuboCop](https://github.com/rubocop/rubocop) for linting
- Write descriptive method and variable names
- Add comments for complex logic
- Follow Rails conventions
### JavaScript/Vue.js Standards
- Follow [JavaScript Standard Style](https://standardjs.com/)
- Use [ESLint](https://eslint.org/) for linting
- Write modular, reusable components
- Use meaningful component and variable names
- Follow Vue.js best practices
### Testing Standards
- Write tests for new features
- Maintain or improve test coverage
- Use descriptive test names
- Test both happy path and edge cases
- Mock external dependencies
## Development Environment
Choose your preferred development environment:
Choose the guide that matches your operating system:
<CardGroup cols={2}>
<Card title="macOS Setup" icon="apple" href="/contributing/environment-setup/macos">
Set up development environment on macOS
<Card
title="macOS Setup"
icon="apple"
href="/contributing/project-setup/macos-setup"
>
Complete setup guide for macOS developers
</Card>
<Card title="Ubuntu Setup" icon="ubuntu" href="/contributing/environment-setup/ubuntu">
Set up development environment on Ubuntu Linux
<Card
title="Ubuntu Setup"
icon="ubuntu"
href="/contributing/project-setup/ubuntu-setup"
>
Step-by-step Ubuntu installation guide
</Card>
<Card title="Windows Setup" icon="windows" href="/contributing/environment-setup/windows">
Set up development environment on Windows
<Card
title="Windows Setup"
icon="windows"
href="/contributing/project-setup/windows-setup"
>
Windows 10/11 development environment setup
</Card>
<Card title="Docker Setup" icon="docker" href="/contributing/environment-setup/docker">
Use Docker for consistent development environment
<Card
title="Docker Setup"
icon="docker"
href="/contributing/project-setup/docker-setup"
>
Quick setup using Docker containers
</Card>
</CardGroup>
## Issue Labels
### Speed Up Development
Understanding our issue labels helps you find the right issues to work on:
Use our [Make commands](/contributing/project-setup/make-setup) to speed up your local development workflow.
| Label | Description |
|-------|-------------|
| `good first issue` | Perfect for new contributors |
| `help wanted` | Community help needed |
| `bug` | Something isn't working |
| `enhancement` | New feature or improvement |
| `documentation` | Documentation improvements |
| `question` | Further information requested |
| `wontfix` | This will not be worked on |
| `duplicate` | This issue already exists |
## Project Setup
Once you have set up the environment, follow these guides to get Chatwoot running locally:
1. **[Quick Setup Guide](/contributing/project-setup/setup-guide)** - Step-by-step setup instructions
2. **[Environment Variables](/contributing/project-setup/environment-variables)** - Configuration options
3. **[Common Errors](/contributing/project-setup/common-errors)** - Troubleshooting guide
### Special App Integrations
If you're working on specific integrations:
- **[Telegram App Setup](/contributing/project-setup/telegram-app)**
- **[Line App Setup](/contributing/project-setup/line-app)**
- **[Mobile App Development](/contributing/project-setup/mobile-app)**
## 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](/contributing/testing)
### Running Tests
```bash
# 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](https://www.chatwoot.com/docs/contributing-guide/other/translation-guidelines)
### Internationalization
- All user-facing text must be translatable
- Only add English strings - other languages are handled via [Crowdin](https://translate.chatwoot.com/)
- Use proper i18n keys and formatting
## Community Guidelines
### Be Respectful
We strive to maintain a welcoming and inclusive community:
- Treat everyone with respect and kindness
- Be patient with new contributors
- Provide constructive feedback
- Help others learn and grow
- **[Code of Conduct](https://www.chatwoot.com/docs/contributing-guide/other/code-of-conduct)** - Our community standards
- **[Community Guidelines](https://www.chatwoot.com/docs/contributing-guide/other/community-guidelines)** - How we interact
- **[Security Reports](https://www.chatwoot.com/docs/contributing-guide/other/security-reports)** - Reporting security issues
### Communication
## API Development
- Use clear, concise language
- Ask questions when unsure
- Share knowledge and resources
- Be responsive to feedback
If you're working on API-related features:
### Collaboration
- Work together towards common goals
- Share credit for collaborative work
- Help review others' contributions
- Mentor new contributors
## Getting Help
If you need help while contributing:
### Documentation
- Read our comprehensive guides
- Check the API documentation
- Review existing code examples
### Community Support
- **Discord**: [Join our community chat](https://discord.gg/cJXdrwS)
- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/chatwoot/chatwoot/discussions)
- **Issues**: Create an issue for bugs or feature requests
### Maintainer Support
- Tag maintainers in issues or PRs when needed
- Be patient - maintainers are volunteers
- Provide detailed information when asking for help
- **[Chatwoot APIs](https://www.chatwoot.com/docs/contributing-guide/other/chatwoot-apis)** - API development guide
- **[API Documentation](https://www.chatwoot.com/docs/contributing-guide/other/api-documentation)** - Documenting APIs
- **[Platform APIs](https://www.chatwoot.com/docs/contributing-guide/other/chatwoot-platform-apis)** - Platform-level APIs
## Recognition
We value all contributions and recognize contributors in several ways:
We value all contributions to Chatwoot. Check out our [Contributors page](https://www.chatwoot.com/docs/contributing-guide/other/contributors) to see the amazing people who have helped make Chatwoot better.
- **Contributors Page**: Listed on our website and README
- **Release Notes**: Mentioned in release announcements
- **Social Media**: Highlighted on our social channels
- **Swag**: Occasional contributor swag for significant contributions
## Getting Help
## Code of Conduct
Need assistance? Here are your options:
All contributors must follow our [Code of Conduct](https://github.com/chatwoot/chatwoot/blob/develop/CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for everyone.
## Next Steps
Ready to start contributing? Here's what to do next:
1. **Set up your development environment** using one of our setup guides
2. **Find a good first issue** to work on
3. **Fork the repository** and create a feature branch
4. **Make your changes** following our guidelines
5. **Submit a pull request** with a clear description
- **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
---
<Note>
Remember, contributing to open source is a learning process. Don't be afraid to ask questions, make mistakes, and learn from the community. Every contribution, no matter how small, makes a difference!
</Note>
<Tip>
Start small with documentation improvements or bug fixes to get familiar with the codebase and contribution process before tackling larger features.
</Tip>
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! 🚀