Contributing

Learn how to contribute to WireChat development

Contributing to WireChat

Thank you for considering contributing to WireChat! This guide will help you get started with contributing code, reporting bugs, and suggesting improvements.

WireChat is an open-source project maintained by Namu Makwembo. Your contributions help make it better for everyone.

Ways to Contribute

There are many ways you can contribute to WireChat:

• 🐛 Report bugs - Help identify issues and edge cases
• 💡 Suggest features - Propose new functionality or improvements
• 📝 Improve documentation - Fix typos, add examples, clarify concepts
• 💻 Submit code - Fix bugs, implement features, refactor code
• 🧪 Write tests - Improve test coverage and reliability
• 🎨 Improve UI/UX - Enhance components, themes, and accessibility

Getting Started

1. Step 1: Fork the Repository
2. Fork the WireChat repository to your GitHub account:
3. gh repo fork namumakwembo/wirechat --clone
   

4. Or visit github.com/namumakwembo/wirechat and click “Fork”.
5. Step 2: Set Up Your Development Environment
6. Clone your fork and install dependencies:
7. cd wirechat
   composer install
   npm install
   

8. Step 3: Configure Git Hooks
9. WireChat uses Git hooks for automated checks. They’re configured automatically on install:
10. "post-install-cmd": [
        "git config core.hooksPath .githooks || true"
    ]
    

11. This runs code quality checks before commits.
12. Step 4: Run the Test Suite
13. Ensure all tests pass before making changes:
14. composer test
    

15. This runs:
17. Run individual tools:

    composer run pest          # Tests only
    composer run lint          # PHPStan only  
    vendor/bin/pint           # Code style only
    
18. Step 5: Start the Development Server
19. WireChat uses Laravel Testbench for development:
20. composer serve
    

21. This:

Development Workflow

Creating a New Feature

1. Step 1: Create a Feature Branch
2. Always create a new branch for your work:
3. git checkout -b feature/your-feature-name
   

4. Use descriptive branch names:
6. Step 2: Make Your Changes
7. Follow these guidelines:
8. Code Style

   WireChat uses Laravel Pint for code formatting:

   vendor/bin/pint
   

   This enforces PSR-12 standards with Laravel-specific rules.

9. Type Safety

   Use PHPStan (level 5+) for static analysis:

   composer run lint
   

   Add proper type hints to all methods:

   public function addParticipant(
       Model $user, 
       ParticipantRole $role = ParticipantRole::PARTICIPANT,
       bool $undoAdminRemovalAction = false
   ): Participant {
       // ...
   }
   
10. Documentation Comments

    Add PHPDoc blocks for complex methods:

    /**
     * Add a new participant to the conversation.
     *
     * @param  Model  $user  The user to add as participant
     * @param  ParticipantRole  $role  The role to assign
     * @param  bool  $undoAdminRemovalAction  Whether to undo admin removal
     * @return Participant  The created participant instance
     */
    public function addParticipant(...) { }
    
11. Database Queries

    • Use Eloquent relationships when possible
    • Eager load to prevent N+1 queries
    • Add database indexes for performance
    • Use transactions for multi-step operations

    Example from Conversation.php:86-102:

    DB::transaction(function () use ($conversation) {
        $conversation->participants()->withoutGlobalScopes()->forceDelete();
        $conversation->messages()?->withoutGlobalScopes()?->forceDelete();
        $conversation->actions()?->delete();
        $conversation->group()?->delete();
    });
    
12. Step 3: Write Tests
13. Add tests for all new features and bug fixes:
14. use Wirechat\Wirechat\Models\Conversation;
    use Wirechat\Wirechat\Enums\ConversationType;
    
    test('can create a private conversation', function () {
        $user1 = User::factory()->create();
        $user2 = User::factory()->create();
        
        $conversation = Conversation::create([
            'type' => ConversationType::PRIVATE,
        ]);
        
        $conversation->addParticipant($user1);
        $conversation->addParticipant($user2);
        
        expect($conversation->participants)->toHaveCount(2);
    });
    

15. Run your tests:
16. vendor/bin/pest
    

17. Step 4: Commit Your Changes
18. Write clear, descriptive commit messages:
19. git add .
    git commit -m "feat: add panel-specific notification settings"
    

20. Follow Conventional Commits:
22. Step 5: Push and Create a Pull Request
23. Push your branch:
24. git push origin feature/your-feature-name
    

25. Create a pull request on GitHub:
26. gh pr create --title "Add panel-specific notification settings" --body "Implements per-panel notification configuration..."
    

Pull Request Guidelines

1. Clear Description
2. Your PR should include:
4. Example:
5. ## What
   Adds support for panel-specific notification settings.
   
   ## Why
   Users requested the ability to configure different notification
   behavior for admin vs. user panels.
   
   ## How
   - Added `notifications()` method to Panel class
   - Updated `NotifyParticipant` to check panel config
   - Added tests for notification scoping
   
   ## Testing
   - ✅ All existing tests pass
   - ✅ Added 5 new tests for notification scoping
   - ✅ Manually tested in workbench app
   

6. Keep PRs Focused
8. Ensure CI Passes
9. Your PR must pass all checks:
11. Fix any failures before requesting review.
12. Request Review
13. Once ready, request review from maintainers. Be responsive to feedback and willing to make changes.

Reporting Bugs

WireChat is in beta. Please report any bugs you find to help stabilize the package.

When reporting bugs, include:

1. WireChat Version - e.g., v0.3.0-beta4
2. Laravel Version - e.g., Laravel 11.x
3. PHP Version - e.g., PHP 8.2
4. Database - MySQL, PostgreSQL, SQLite, etc.
5. Steps to Reproduce - Minimal code to trigger the bug
6. Expected Behavior - What should happen
7. Actual Behavior - What actually happens
8. Error Messages - Full stack traces if available

Use the issue template on GitHub.

Suggesting Features

Before suggesting a feature:

1. Check existing issues for duplicates
2. Search discussions
3. Consider if it fits WireChat’s scope and philosophy

When proposing features, explain:

• Use case - What problem does it solve?
• API design - How would developers use it?
• Alternatives - What workarounds exist today?
• Breaking changes - Would it affect existing code?

Code of Conduct

Be respectful, inclusive, and professional in all interactions. WireChat follows standard open-source community guidelines.

Key principles:

• Be respectful - Value diverse perspectives
• Be constructive - Provide helpful feedback
• Be patient - Maintainers are volunteers
• Be collaborative - Work together toward solutions

Recognition

All contributors are recognized in:

• GitHub contributor graphs
• Release notes for significant contributions
• The WireChat documentation

Support the Project

If you can’t contribute code, you can still help:

• ⭐ Star the repo on GitHub
• 💬 Share WireChat with others
• 💰 Sponsor the project via GitHub Sponsors
• ☕ Buy the maintainer a coffee via Buy Me a Coffee

Your support—whether code, feedback, or sponsorship—helps keep WireChat actively maintained and improved.

Documentation Contributions

The documentation site is built with Mintlify. To contribute:

1. Documentation source is at wirechat.namuio.com/docs/contribution
2. Follow the same PR workflow as code contributions
3. Preview locally using Mintlify CLI
4. Ensure MDX syntax is valid

Questions?

If you have questions about contributing:

• 💬 Ask in GitHub Discussions
• 🐦 Reach out on Twitter/X
• 📧 Contact the maintainer directly

For more details, see the full contribution guide at wirechat.namuio.com/docs/contribution.