GitHub Repository

​

Swarms on GitHub

​

Reporting Issues

​

Before Reporting

1. Search Existing Issues: Check if someone has already reported the issue
   • Search open issues
   • Check closed issues too - your issue may have been resolved
2. Verify It’s a Bug: Make sure it’s actually a bug and not expected behavior
   • Check the documentation
   • Look at the examples
   • Ask in Discord if you’re unsure

​

Creating a Bug Report

1. Clear Title: A concise summary of the issue
   • Good: “Agent fails when using tools with streaming enabled”
   • Bad: “Agent broken”
2. Description: Detailed information about the bug
   • What you were trying to do
   • What you expected to happen
   • What actually happened
3. Steps to Reproduce: Exact steps to reproduce the issue
   1. Create an agent with model_name="gpt-5.4"
   2. Enable streaming with stream=True
   3. Add a tool to the agent
   4. Run the agent with a task
   5. Observe the error
   
4. Code Sample: Minimal reproducible example
   from swarms import Agent
   
   agent = Agent(
       agent_name="TestAgent",
       model_name="gpt-5.4",
       stream=True
   )
   
   # This causes the error
   result = agent.run("Test task")
   
5. Error Messages: Include the full error message and stack trace
   Traceback (most recent call last):
     File "test.py", line 8, in <module>
       result = agent.run("Test task")
     ...
   AttributeError: 'NoneType' object has no attribute 'run'
   
6. Environment Information:
   • Operating System (e.g., macOS 14.0, Ubuntu 22.04, Windows 11)
   • Python version (e.g., 3.10.5)
   • Swarms version (e.g., 6.5.0)
   • Relevant dependency versions
7. Additional Context: Screenshots, logs, or other helpful information

​

Using Issue Templates

• Bug Report Template
• Feature Request Template

​

Requesting Features

​

Before Requesting

1. Check Existing Requests: Search for similar feature requests
2. Review the Roadmap: Check the project board
3. Discuss on Discord: Get community feedback on Discord

​

Creating a Feature Request

1. Clear Title: Describe the feature concisely
   • Good: “Add support for async agent execution”
   • Bad: “Make it better”
2. Problem Statement: Explain the problem this feature solves
   Currently, agents can only run synchronously, which limits performance
   when orchestrating multiple agents that could work in parallel.
   
3. Proposed Solution: Describe how you envision the feature working
   # Example of desired API
   async def run_agents():
       agent1 = Agent(agent_name="Agent1")
       agent2 = Agent(agent_name="Agent2")
       
       results = await asyncio.gather(
           agent1.run_async("Task 1"),
           agent2.run_async("Task 2")
       )
       return results
   
4. Alternatives Considered: Other approaches you’ve thought about
5. Use Cases: Real-world scenarios where this would be useful
6. Benefits: How this feature would improve Swarms

​

Contributing Code

​

Getting Started

1. Fork the Repository: Create your own copy
   • Click the “Fork” button on GitHub
2. Clone Your Fork: Download to your local machine
   git clone https://github.com/YOUR_USERNAME/swarms.git
   cd swarms
   
3. Set Up Development Environment: Follow the development setup guide

​

Making Changes

1. Create a Branch: Use a descriptive name
   git checkout -b feature/add-async-support
   
2. Make Your Changes: Follow the coding standards
3. Write Tests: Ensure your changes are tested
   pytest tests/
   
4. Update Documentation: Document your changes

​

Submitting a Pull Request

1. Push Your Changes:
   git push origin feature/add-async-support
   
2. Create Pull Request: On GitHub, click “New Pull Request”
3. Fill Out PR Template: Provide:
   • Description: What changes you made and why
   • Related Issues: Link to related issues (e.g., “Fixes #123”)
   • Type of Change: Bug fix, new feature, documentation, etc.
   • Testing: How you tested your changes
   • Screenshots: If applicable
4. Wait for Review: Maintainers will review your PR
   • Be responsive to feedback
   • Make requested changes promptly
   • Keep the conversation professional

​

PR Best Practices

# Good
git commit -m "Add async support for agent execution"

# Bad
git commit -m "updates"

​

Finding Issues to Work On

​

Good First Issues

• Good First Issues
• Specifically selected for newcomers
• Well-documented and scoped
• Mentorship available

​

Help Wanted

• Help Wanted Issues
• Issues where maintainers need assistance
• More complex problems
• High impact on the project

​

Project Board

• Contributing Board
• See what’s being worked on
• Find areas that need help
• Participate in planning discussions

​

GitHub Workflow

​

Issue Labels

• bug: Something isn’t working
• enhancement: New feature or request
• documentation: Improvements or additions to documentation
• good first issue: Good for newcomers
• help wanted: Extra attention is needed
• question: Further information is requested
• wontfix: This will not be worked on

​

Milestones

• View active milestones
• See what’s planned for upcoming releases
• Track progress toward release goals

​

Repository Structure

swarms/
├── swarms/              # Main package source code
│   ├── agents/          # Agent implementations
│   ├── structs/         # Swarm structures
│   ├── tools/           # Tool implementations
│   └── utils/           # Utility functions
├── examples/            # Example scripts
├── tests/               # Test suite
├── docs/                # Documentation
├── CONTRIBUTING.md      # Contribution guidelines
├── CODE_OF_CONDUCT.md   # Code of conduct
└── README.md            # Project README

​

Getting Help with GitHub

• Ask in the #contributors channel on Discord
• Check the GitHub documentation
• Schedule an onboarding session

​

Recognition

​

Contributors Wall

​

Community Acknowledgment

• Featured in release notes
• Mentioned in community calls
• Recognition on social media