From 37af13085c05202bf69b4a1d2bace8576c2d647a Mon Sep 17 00:00:00 2001 From: bordumb Date: Sun, 25 Jan 2026 01:51:09 +0000 Subject: [PATCH 1/2] docs: add CONTRIBUTING.md Comprehensive contributing guide covering: - Bug reporting and feature requests - Development setup with uv - Branch naming and commit message conventions - Pull request process - Code style (ruff, mypy, pre-commit) - Testing guidelines - Documentation standards - Project structure overview Co-Authored-By: Claude Opus 4.5 --- CONTRIBUTING.md | 314 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a5b6760 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,314 @@ +# Contributing to Bond + +Thank you for your interest in contributing to Bond! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Making Changes](#making-changes) +- [Pull Request Process](#pull-request-process) +- [Code Style](#code-style) +- [Testing](#testing) +- [Documentation](#documentation) + +## Code of Conduct + +Please be respectful and constructive in all interactions. We welcome contributors of all backgrounds and experience levels. + +## Getting Started + +### Reporting Bugs + +Before reporting a bug: + +1. Search [existing issues](https://github.com/renbytes/bond-agent/issues) to avoid duplicates +2. If none exists, [open a new issue](https://github.com/renbytes/bond-agent/issues/new) with: + - A clear, descriptive title + - Steps to reproduce the issue + - Expected vs actual behavior + - Python version and OS + - Relevant error messages or stack traces + +### Suggesting Features + +Feature requests are welcome! Please: + +1. Check [existing issues](https://github.com/renbytes/bond-agent/issues) for similar requests +2. Open a new issue describing: + - The use case or problem you're solving + - Your proposed solution + - Any alternatives you've considered + +### First-Time Contributors + +Look for issues labeled [`good first issue`](https://github.com/renbytes/bond-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for beginner-friendly tasks. + +## Development Setup + +### Prerequisites + +- **Python 3.11+** (3.11 or 3.12 recommended) +- **uv** package manager ([installation guide](https://docs.astral.sh/uv/getting-started/installation/)) +- **Git** + +### Setup Steps + +```bash +# 1. Fork the repository on GitHub + +# 2. Clone your fork +git clone https://github.com/YOUR_USERNAME/bond-agent.git +cd bond-agent + +# 3. Add upstream remote +git remote add upstream https://github.com/renbytes/bond-agent.git + +# 4. Install dependencies +uv sync --group dev + +# 5. Install pre-commit hooks +uv run pre-commit install + +# 6. Verify setup +uv run pytest +``` + +## Making Changes + +### Branch Naming + +Create a branch from `main` with a descriptive name: + +```bash +git checkout main +git pull upstream main +git checkout -b type/short-description +``` + +Branch types: +- `feat/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation only +- `refactor/` - Code refactoring +- `test/` - Test additions or fixes + +### Commit Messages + +Write clear, concise commit messages: + +``` +type: short description + +Longer explanation if needed. Wrap at 72 characters. + +- Bullet points are fine +- Explain what and why, not how +``` + +Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` + +Examples: +- `feat: add GitHub repository search tool` +- `fix: handle rate limit errors in GitHub adapter` +- `docs: add streaming server guide` + +## Pull Request Process + +1. **Update your branch** with the latest upstream changes: + ```bash + git fetch upstream + git rebase upstream/main + ``` + +2. **Run all checks** before pushing: + ```bash + uv run pre-commit run --all-files + uv run pytest + ``` + +3. **Push your branch** and open a PR: + ```bash + git push origin your-branch-name + ``` + +4. **Fill out the PR template** with: + - Summary of changes + - Link to related issues + - Test plan + +5. **Address review feedback** promptly + +### PR Requirements + +- All CI checks must pass +- Code must be formatted and linted +- New features require tests +- Documentation updates for user-facing changes + +## Code Style + +### Formatting and Linting + +Bond uses [Ruff](https://docs.astral.sh/ruff/) for formatting and linting: + +```bash +# Format code +uv run ruff format src tests + +# Lint and auto-fix +uv run ruff check --fix src tests +``` + +### Type Checking + +Bond uses strict [mypy](https://mypy.readthedocs.io/) type checking: + +```bash +uv run mypy src/bond +``` + +All new code must be fully typed. Key rules: +- No `Any` types without justification +- All function parameters and returns typed +- Use `Protocol` for duck typing + +### Pre-commit Hooks + +Pre-commit runs automatically on each commit: + +```bash +# Run manually +uv run pre-commit run --all-files +``` + +Hooks: +1. `ruff format` - Auto-formats code +2. `ruff check --fix` - Lints and auto-fixes +3. `mypy` - Type checks + +## Testing + +### Running Tests + +```bash +# Run all tests with coverage +uv run pytest + +# Run specific test file +uv run pytest tests/unit/tools/github/test_adapter.py + +# Run tests matching a pattern +uv run pytest -k "github" + +# Run with verbose output +uv run pytest -v +``` + +### Writing Tests + +- Place tests in `tests/` mirroring the `src/` structure +- Use `pytest` fixtures for setup +- Use `respx` for mocking HTTP requests +- Aim for high coverage on new code + +Example test: + +```python +import pytest +from bond.tools.github import GitHubAdapter + +@pytest.fixture +def adapter(): + return GitHubAdapter(token="test-token") + +async def test_get_repo_returns_info(adapter, respx_mock): + respx_mock.get("https://api.github.com/repos/owner/repo").respond( + json={"name": "repo", "description": "A test repo"} + ) + + result = await adapter.get_repo("owner", "repo") + + assert result.name == "repo" + assert result.description == "A test repo" +``` + +## Documentation + +### Building Docs + +```bash +# Install docs dependencies +uv sync --extra docs + +# Serve locally with hot reload +uv run mkdocs serve + +# Build and check for errors +uv run mkdocs build --strict +``` + +### Documentation Guidelines + +- Update docs for user-facing changes +- Use Google-style docstrings +- Include code examples +- Keep API reference in `docs/api/` in sync + +### Docstring Example + +```python +def get_repo(self, owner: str, repo: str) -> RepoInfo: + """Get repository metadata. + + Args: + owner: Repository owner (user or organization). + repo: Repository name. + + Returns: + Repository information including description, stars, and topics. + + Raises: + RepoNotFoundError: If the repository doesn't exist. + RateLimitedError: If API rate limit is exceeded. + """ +``` + +## Project Structure + +``` +src/bond/ +├── __init__.py # Package exports +├── agent.py # BondAgent implementation +├── utils.py # StreamHandlers utilities +├── server/ # HTTP server module +├── tools/ # Bundled toolsets +│ ├── github/ # GitHub API tools +│ ├── githunter/ # Git forensics tools +│ ├── memory/ # Semantic memory tools +│ └── schema/ # Schema extraction tools +└── trace/ # Execution tracing +``` + +### Adding a New Toolset + +See [Adding Tools](https://renbytes.github.io/bond-agent/development/adding-tools/) for the complete guide. + +Each toolset follows this structure: + +``` +tools/my_tool/ +├── __init__.py # Public API exports +├── _protocols.py # Protocol definition +├── _types.py # Pydantic models +├── _adapter.py # Protocol implementation +└── tools.py # Tool functions +``` + +## Questions? + +- Open a [GitHub Discussion](https://github.com/renbytes/bond-agent/discussions) for questions +- Check the [documentation](https://renbytes.github.io/bond-agent/) for guides + +Thank you for contributing! From 087159d1c8689ca48dbc506368b768c3dc6003eb Mon Sep 17 00:00:00 2001 From: bordumb Date: Sun, 25 Jan 2026 01:55:41 +0000 Subject: [PATCH 2/2] docs: add GitHub issue templates Add structured issue templates: - Bug report with reproduction steps, code examples, version info - Feature request with use case, API design, component selection - Question template for usage help - Config to disable blank issues and add contact links Co-Authored-By: Claude Opus 4.5 --- .github/ISSUE_TEMPLATE/bug_report.yml | 107 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 76 +++++++++++++++ .github/ISSUE_TEMPLATE/question.yml | 51 ++++++++++ 4 files changed, 242 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..0026c11 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,107 @@ +name: Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug! Please fill out the information below to help us investigate. + + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of the bug. + placeholder: What happened? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Minimal steps to reproduce the behavior. + placeholder: | + 1. Create a BondAgent with... + 2. Call agent.ask(...) + 3. See error... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? Include error messages and stack traces if applicable. + validations: + required: true + + - type: textarea + id: code + attributes: + label: Minimal Reproducible Example + description: If possible, provide a minimal code example that reproduces the issue. + render: python + placeholder: | + from bond import BondAgent + + agent = BondAgent( + name="test", + instructions="You are helpful.", + model="openai:gpt-4o", + ) + + # This causes the bug... + result = await agent.ask("Hello") + + - type: dropdown + id: version + attributes: + label: Bond Version + description: What version of bond-agent are you using? + options: + - "0.1.2 (latest)" + - "0.1.1" + - "0.1.0" + - "main branch" + - "Other (specify in description)" + validations: + required: true + + - type: dropdown + id: python + attributes: + label: Python Version + options: + - "3.12" + - "3.11" + - "Other" + validations: + required: true + + - type: dropdown + id: os + attributes: + label: Operating System + options: + - "macOS" + - "Linux" + - "Windows" + - "Other" + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..eba05c6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation + url: https://renbytes.github.io/bond-agent/ + about: Check the documentation for guides and API reference + - name: Discussions + url: https://github.com/renbytes/bond-agent/discussions + about: Ask questions and share ideas in GitHub Discussions diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..9c59bc6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,76 @@ +name: Feature Request +description: Suggest a new feature or enhancement +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please describe your idea below. + + - type: textarea + id: problem + attributes: + label: Problem or Use Case + description: What problem are you trying to solve? What use case does this enable? + placeholder: | + I'm trying to build an agent that... + Currently I have to work around this by... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe your proposed solution or feature. + placeholder: | + It would be great if BondAgent could... + validations: + required: true + + - type: textarea + id: api + attributes: + label: API Design (Optional) + description: If you have thoughts on the API, share them here. + render: python + placeholder: | + # Example of how the feature might work + agent = BondAgent( + name="assistant", + new_feature=True, # New option + ) + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Any alternative solutions or features you've considered? + + - type: dropdown + id: component + attributes: + label: Component + description: Which part of Bond does this relate to? + options: + - "Core (BondAgent, streaming)" + - "Server (SSE, WebSocket)" + - "Tools - GitHub" + - "Tools - GitHunter" + - "Tools - Memory" + - "Tools - Schema" + - "Tools - New toolset" + - "Trace/Observability" + - "Documentation" + - "Other" + validations: + required: true + + - type: checkboxes + id: contribution + attributes: + label: Contribution + description: Would you be interested in contributing this feature? + options: + - label: I'd be willing to submit a PR for this feature diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..4710d96 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,51 @@ +name: Question +description: Ask a question about using Bond +title: "[Question]: " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + Have a question about using Bond? We're happy to help! + + **Before asking:** + - Check the [documentation](https://renbytes.github.io/bond-agent/) + - Search [existing issues](https://github.com/renbytes/bond-agent/issues) + + - type: textarea + id: question + attributes: + label: Question + description: What would you like to know? + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context + description: What are you trying to accomplish? Any relevant code or configuration? + render: python + + - type: textarea + id: tried + attributes: + label: What I've Tried + description: What have you already tried or looked at? + + - type: dropdown + id: topic + attributes: + label: Topic + options: + - "Getting started / Installation" + - "BondAgent configuration" + - "Streaming / StreamHandlers" + - "Server setup (SSE/WebSocket)" + - "Using tools (GitHub, Memory, etc.)" + - "Creating custom tools" + - "Tracing / Observability" + - "Testing" + - "Other" + validations: + required: true