Skip to main content

How to Contribute

Guidelines for contributing to the Pixell project.

Note: This documentation is generated by AI based on the source code, and therefore it may have some incorrect knowledge of the project. In that case, please contact engineering@pixell.global

Welcome Contributors!​

We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or helping others, your contributions make Pixell better for everyone.

Types of Contributions​

Code Contributions​

  • Bug fixes - Fix issues and improve stability
  • New features - Add functionality to existing components
  • Performance improvements - Optimize code and reduce resource usage
  • Refactoring - Improve code quality and maintainability

Documentation Contributions​

  • User guides - Improve existing documentation
  • API documentation - Document functions, classes, and methods
  • Examples - Add code examples and tutorials
  • Translations - Translate documentation to other languages

Community Contributions​

  • Issue triage - Help categorize and prioritize issues
  • Code reviews - Review pull requests and provide feedback
  • Testing - Test new features and report bugs
  • Support - Help other users in discussions and forums

Getting Started​

1. Set Up Development Environment​

# Clone the repository
git clone https://github.com/pixell-global/pixell.git
cd pixell

# Install dependencies
npm install

# Set up development environment
npm run dev:setup

2. Choose What to Work On​

  • Good first issues - Look for issues labeled good first issue
  • Bug reports - Check the issues list for bugs you can fix
  • Feature requests - Implement requested features
  • Documentation - Improve existing docs or add new ones

3. Create a Branch​

# Create a new branch for your work
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
# or
git checkout -b docs/your-documentation-update

Contribution Process​

1. Fork and Clone​

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/your-username/pixell.git
cd pixell
git remote add upstream https://github.com/pixell-global/pixell.git

2. Make Changes​

  • Write clean, readable code
  • Follow the coding standards
  • Add tests for new functionality
  • Update documentation as needed
  • Ensure all tests pass

3. Test Your Changes​

# Run the test suite
npm test

# Run linting
npm run lint

# Run type checking
npm run type-check

# Run build to ensure everything compiles
npm run build

4. Commit Your Changes​

# Add your changes
git add .

# Commit with a descriptive message
git commit -m "feat: add new feature for agent communication

- Implement gRPC-based agent-to-agent communication
- Add service discovery integration
- Include comprehensive error handling
- Add unit tests for new functionality

Fixes #123"

5. Push and Create Pull Request​

# Push your branch
git push origin feature/your-feature-name

# Create a pull request on GitHub

Coding Standards​

Code Style​

  • Python: Follow PEP 8 style guide
  • JavaScript/TypeScript: Use Prettier and ESLint
  • Go: Follow standard Go formatting
  • Rust: Use rustfmt for formatting

Documentation​

  • Write clear, concise comments
  • Document all public APIs
  • Include examples in docstrings
  • Update README files when adding features

Testing​

  • Write unit tests for new functionality
  • Include integration tests for complex features
  • Ensure test coverage doesn't decrease
  • Test edge cases and error conditions

Pull Request Guidelines​

Before Submitting​

  • Code follows project style guidelines
  • All tests pass
  • Documentation is updated
  • Commit messages are clear and descriptive
  • Branch is up to date with main

Pull Request Template​

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or breaking changes documented)

Review Process​

  1. Automated checks - CI/CD pipeline runs tests and linting
  2. Code review - Maintainers review the code
  3. Testing - Changes are tested in staging environment
  4. Approval - Maintainer approves the pull request
  5. Merge - Changes are merged into main branch

Issue Guidelines​

Reporting Bugs​

When reporting bugs, please include:

  • Description - Clear description of the issue
  • Steps to reproduce - Detailed steps to reproduce the bug
  • Expected behavior - What should happen
  • Actual behavior - What actually happens
  • Environment - OS, version, configuration details
  • Logs - Relevant error messages or logs

Requesting Features​

When requesting features, please include:

  • Use case - Why is this feature needed?
  • Proposed solution - How should it work?
  • Alternatives - Other ways to solve the problem
  • Additional context - Any other relevant information

Development Workflow​

Branch Naming​

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring
  • test/description - Test improvements

Commit Messages​

Follow the conventional commits format:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Test changes
  • chore: Build process or auxiliary tool changes

Release Process​

  1. Version bump - Update version numbers
  2. Changelog - Update CHANGELOG.md
  3. Release notes - Create release notes
  4. Tag release - Create git tag
  5. Publish - Publish to package registries

Community Guidelines​

Code of Conduct​

  • Be respectful and inclusive
  • Welcome newcomers and help them learn
  • Focus on what's best for the community
  • Show empathy towards other community members

Communication​

  • GitHub Issues - Bug reports and feature requests
  • GitHub Discussions - General questions and ideas
  • Discord - Real-time chat and support
  • Email - engineering@pixell.global for private matters

Getting Help​

  • Check existing issues and discussions first
  • Search documentation and examples
  • Ask questions in GitHub Discussions
  • Join our Discord community
  • Contact maintainers for urgent issues

Recognition​

Contributors​

We recognize contributors in several ways:

  • Contributors list - Listed in README and documentation
  • Release notes - Mentioned in release announcements
  • Badges - GitHub contributor badges
  • Swag - Pixell merchandise for significant contributions

Maintainers​

Maintainers are contributors who have demonstrated:

  • Consistent high-quality contributions
  • Deep understanding of the codebase
  • Ability to help other contributors
  • Commitment to the project's goals

Development Resources​

Documentation​

Tools​

  • IDE: VS Code with recommended extensions
  • Testing: Jest, pytest, go test
  • Linting: ESLint, Prettier, flake8, golint
  • CI/CD: GitHub Actions
  • Monitoring: Sentry, DataDog

External Resources​

Questions?​

If you have questions about contributing:

  1. Check the FAQ section below
  2. Search existing GitHub Discussions
  3. Ask in our Discord community
  4. Contact us at engineering@pixell.global

FAQ​

Q: How do I get started with my first contribution?​

A: Look for issues labeled good first issue or help wanted. These are specifically chosen to be beginner-friendly.

Q: What if I'm not sure about the implementation approach?​

A: Open a draft pull request or create an issue to discuss the approach with maintainers before implementing.

Q: How long does it take for a pull request to be reviewed?​

A: We aim to review pull requests within 48 hours. For urgent fixes, contact maintainers directly.

Q: Can I contribute to documentation even if I'm not a developer?​

A: Absolutely! Documentation contributions are just as valuable as code contributions.

Q: What if my pull request is rejected?​

A: Don't be discouraged! Maintainers will provide feedback to help you improve. Use the feedback to make your contribution even better.

Next Steps​

Ready to contribute? Here's what to do next:

  1. Code Structure - Understand the codebase organization
  2. Build from Source - Set up your development environment
  3. Roadmap - See what features are planned
  4. Find an issue - Look for good first issue labels
  5. Start coding - Make your first contribution!

Thank you for contributing to Pixell! 🚀