How to Contribute

Thank you for considering contributing to Beever Atlas! We welcome contributions from everyone, whether you're fixing bugs, adding features, improving documentation, or sharing ideas.

Ways to Contribute

Getting Started

Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork:

git clone https://github.com/your-username/beever-atlas.git
cd beever-atlas

3. Add upstream remote:

git remote add upstream https://github.com/beever-atlas/beever-atlas.git

Set Up Development Environment

See the Development Setup guide for detailed instructions.

Quick start:

# Install Python dependencies
uv sync

# Install bot dependencies
cd bot && npm install

# Start infrastructure
docker compose up -d

# Run the backend
uv run uvicorn beever_atlas.server.app:app --reload

# Run the frontend (in another terminal)
cd web && npm run dev

Making Changes

Branch Naming

Use descriptive branch names:

• fix/description-of-bug for bug fixes
• feature/description-of-feature for new features
• docs/description-of-change for documentation
• refactor/description-of-refactor for refactoring

Commit Messages

Follow conventional commits format:

type(scope): description

[optional body]

[optional footer]

Types:

• fix: Bug fix
• feat: New feature
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Build process or tooling changes

Examples:

fix(slack): handle rate limit errors gracefully

feat(api): add streaming support for ask endpoint

docs(contributing): add pull request guidelines

Code Style

Follow the project's code style:

Pull Request Process

Before Submitting

# Python
uv run ruff check .
uv run ruff format .

# TypeScript
cd bot && npm run lint && npm run format

git fetch upstream
git rebase upstream/main

Submitting a PR

1. Push to your fork:

git push origin feature/your-feature-name

2. Create a Pull Request on GitHub

3. Fill out the PR template:

• Description of changes
• Related issues (fixes #123)
• Testing steps
• Screenshots (if applicable)

4. Wait for review

• Address review feedback
• Make requested changes
• Keep the conversation going

Review Guidelines

As a contributor, you can also review PRs:

• Be constructive and respectful
• Ask questions if something is unclear
• Suggest improvements
• Test the changes if possible

Issue Templates

Bug Report

When reporting a bug, include:

Description

• Clear description of the problem
• Expected behavior
• Actual behavior
• Steps to reproduce

Environment

• OS and version
• Python/Node version
• Beever Atlas version
• Related configuration

Reproduction

# Commands or code to reproduce

Expected behavior What should happen

Actual behavior What actually happens

Screenshots/logs If applicable

Feature Request

When proposing a feature:

Problem

• What problem does it solve?
• Who is it for?

Proposed Solution

• Detailed description
• API changes (if any)
• UI/UX considerations

Alternatives

• Other approaches considered
• Why this approach is best

Additional Context

• Examples
• Mockups
• References

Development Guidelines

Architecture Decisions

For significant changes, start a discussion first:

1. Open an issue with the design label
2. Describe the problem and proposed solution
3. Get feedback from maintainers
4. Create an ADR (Architecture Decision Record) if needed

Breaking Changes

Avoid breaking changes when possible. If necessary:

1. Clearly document the breakage
2. Provide migration guide
3. Deprecate old functionality first
4. Update all internal usage

Performance

Consider performance impact:

• Profile before optimizing
• Add benchmarks for critical paths
• Document trade-offs

Security

• Never commit secrets or credentials
• Follow security best practices
• Report vulnerabilities privately

Testing

Running Tests

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_specific.py

# Run with coverage
uv run pytest --cov=beever_atlas --cov-report=html

# Run specific test
uv run pytest tests/test_specific.py::test_function

Writing Tests

Follow testing guidelines:

• Use pytest fixtures for common setup
• Mock external services (Slack, Discord, etc.)
• Test both success and failure cases
• Use descriptive test names

Communication

Channels

• GitHub Issues: Bug reports, feature requests
• GitHub Discussions: Questions, ideas
• Discord: Community chat (if available)
• Email: security@beever-atlas.com for security issues

Getting Help

• Check existing issues and discussions
• Read the documentation
• Ask questions in discussions
• Be patient and respectful

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• Project website (with permission)

Thank you for contributing to Beever Atlas!

Code of Conduct

Please read and follow our Code of Conduct.

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.