Skip to main content

Contributing Guide

Thank you for your interest in contributing to the Engineering AI Agent project! This guide will help you get started with the contribution process, from setting up your development environment to submitting your changes.

Getting Started​

Prerequisites​

Before you begin, make sure you have the following installed:

  • Python 3.9+
  • Node.js 18+ and pnpm (for documentation)
  • Git
  • A GitHub account

Fork and Clone​

  1. Fork the repository on GitHub by visiting https://github.com/Chisanan232/Engineering-AI-Agent and clicking the "Fork" button.

  2. Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/Engineering-AI-Agent.git cd Engineering-AI-Agent


3. Add the upstream repository as a remote:
   ```bash
git remote add upstream https://github.com/Chisanan232/Engineering-AI-Agent.git

Set Up Development Environment​

  1. Create and activate a virtual environment:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate


2. Install dependencies:
   ```bash
pip install -r requirements.txt
   pip install -r requirements-dev.txt
  1. Set up pre-commit hooks:

pre-commit install


## Development Workflow

### Create a Branch

Create a branch for your contribution:

```bash
git checkout -b feature/your-feature-name

Use a descriptive name for your branch that reflects the changes you're making:

  • feature/new-feature for new features
  • fix/bug-description for bug fixes
  • docs/documentation-improvement for documentation changes
  • refactor/component-name for code refactoring

Make Changes​

  1. Make your changes to the codebase.
  2. Write or update tests for your changes.
  3. Ensure all tests pass by running:

pytest


4. Make sure your code follows our style guidelines:
   ```bash
flake8
   black .
   isort .

Commit Your Changes​

  1. Stage your changes:

git add .


2. Commit with a descriptive message following our commit message convention:
   ```bash
git commit -m "type(scope): brief description"

Types include:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Example: feat(rd): add support for GitHub PR reviews

  1. Push your changes to your fork:

git push origin feature/your-feature-name


### Open a Pull Request

1. Go to the [Engineering AI Agent repository](https://github.com/Chisanan232/Engineering-AI-Agent/pulls).
2. Click "New Pull Request".
3. Select "compare across forks" if needed.
4. Select your fork and branch.
5. Fill in the PR template with:
   - A clear title
   - A detailed description of your changes
   - Any related issues
   - Screenshots if applicable
   - Notes about testing

### Review Process

After submitting your PR:

1. Automated checks will run to verify your code.
2. Maintainers will review your changes.
3. You may be asked to make adjustments.
4. Once approved, your changes will be merged.

## Contribution Guidelines

### Code Style

We follow these coding standards:
- PEP 8 for Python code
- Black for code formatting
- isort for import sorting
- TypeScript standards for frontend code

### Documentation

If your contribution adds, changes, or removes features:
1. Update the relevant documentation in the `docs/` directory.
2. Add or update JSDoc or docstrings for public APIs.
3. Include code examples where appropriate.

To preview documentation changes:
```bash
cd docs
pnpm install
pnpm start

Testing​

All contributions must include tests:

  • Unit tests for specific functions/classes
  • Integration tests for features that interact with external systems
  • End-to-end tests for complex workflows

Tests should be placed in the tests/ directory, mirroring the package structure.

Git Workflow​

We follow a simplified GitHub flow:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with appropriate commits
  4. Open a pull request
  5. Address review feedback
  6. Maintainers merge approved PRs

Types of Contributions​

Bug Fixes​

If you're fixing a bug:

  1. Check if there's an existing issue; if not, create one.
  2. Reference the issue in your PR.
  3. Include a test that reproduces and fixes the bug.
  4. Explain the root cause of the bug.

Feature Development​

For new features:

  1. Start by opening an issue describing the feature.
  2. Discuss the implementation approach with maintainers.
  3. Implement the feature with appropriate tests and documentation.
  4. Update the CHANGELOG.md file.

Documentation Improvements​

Documentation contributions are welcome:

  • Fix typos or clarify existing documentation
  • Add examples or tutorials
  • Improve API reference documentation
  • Add diagrams or visual aids

Code Refactoring​

When refactoring code:

  1. Clearly explain the improvements being made.
  2. Ensure all tests continue to pass.
  3. Don't mix refactoring with feature changes.

Community​

Communication Channels​

  • GitHub Issues: For bug reports and feature requests
  • Discussions: For questions and community support
  • Slack Channel: For real-time collaboration (invitation in README)

Code of Conduct​

We expect all contributors to follow our Code of Conduct. Please be respectful and inclusive in all interactions.

Recognition​

All contributors are recognized in:

  • The CONTRIBUTORS.md file
  • Release notes for significant contributions
  • Special callouts in documentation when appropriate

Development Tips​

Working with Agent Roles​

When developing new agent role capabilities:

  1. Understand the role's responsibilities and workflows
  2. Follow the established patterns in existing roles
  3. Clearly separate role-specific code from shared utilities
  4. Document the role's capabilities and configuration options

Integration Development​

When adding or enhancing integrations:

  1. Use the integration interface patterns
  2. Provide comprehensive error handling
  3. Include tests with appropriate mocks
  4. Document authentication and setup requirements

Local Testing​

To test the entire system locally:

  1. Configure mock services for external integrations
  2. Set up a local development environment using docker-compose:

docker-compose -f docker-compose.dev.yml up

3. Test role interactions using the provided test scripts

## Release Process

Our release process:
1. Code is merged into the `develop` branch
2. When ready for release, a release branch is created
3. Release candidates are tested
4. Final release is merged to `main` and tagged
5. Documentation is updated

### Version Numbering

We follow semantic versioning (MAJOR.MINOR.PATCH):
- MAJOR: Incompatible API changes
- MINOR: New functionality (backwards-compatible)
- PATCH: Bug fixes (backwards-compatible)

## Getting Help

If you need help with your contribution:
- Check the documentation
- Search existing issues and discussions
- Ask in the community Slack channel
- Reach out to maintainers

Thank you for contributing to the Engineering AI Agent project! Your efforts help make this project better for everyone.