From 4b3de291966d890f933e4732a7e6a827d54b9a92 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 12 Apr 2026 14:28:47 +0000 Subject: [PATCH 1/4] Initial plan From 20d6c1ab4283f0b1b3743f8b39cee9a7da52bd9c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 12 Apr 2026 14:34:34 +0000 Subject: [PATCH 2/4] docs: add PR template, YAML issue forms, and CONTRIBUTING.md Agent-Logs-Url: https://github.com/dgenio/ChainWeaver/sessions/38ffab58-94aa-4aec-8dde-12fafdcec141 Co-authored-by: dgenio <12731907+dgenio@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.yml | 67 +++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 35 +++++++ .github/pull_request_template.md | 21 ++++ CONTRIBUTING.md | 107 +++++++++++++++++++++ 5 files changed, 231 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/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..92c0cca --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,67 @@ +name: Bug Report +description: Report a bug or unexpected behavior in ChainWeaver. +labels: [bug] +body: + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of the bug. + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Minimal steps to reproduce the issue. + placeholder: | + 1. Create a Flow with ... + 2. Call executor.execute_flow(...) + 3. Observe ... + 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 full tracebacks where relevant. + validations: + required: true + + - type: dropdown + id: python_version + attributes: + label: Python version + options: + - "3.10" + - "3.11" + - "3.12" + - "3.13" + validations: + required: true + + - type: input + id: chainweaver_version + attributes: + label: ChainWeaver version + placeholder: "e.g. 0.1.0" + validations: + required: true + + - type: textarea + id: additional_context + attributes: + label: Additional context + description: Any other context, screenshots, or relevant information. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..0086358 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6d3127c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,35 @@ +name: Feature Request +description: Propose a new feature or enhancement for ChainWeaver. +labels: [enhancement] +body: + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of the feature you'd like to see. + validations: + required: true + + - type: textarea + id: use_case + attributes: + label: Use case + description: What problem does this solve? Describe the scenario where this feature would be useful. + validations: + required: true + + - type: textarea + id: proposed_solution + attributes: + label: Proposed solution + description: How would you like this feature to work? Include API sketches or examples if possible. + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What other approaches did you consider? Why is your proposed solution preferable? + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..7aa7284 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +## Summary + + +## Changes + +- + +## Testing + +- [ ] All existing tests pass (`pytest`) +- [ ] New tests added for new functionality +- [ ] Linting passes (`ruff check`) +- [ ] Type checking passes (`mypy`) + +## Related Issues + + +## Checklist +- [ ] Code follows project conventions (see `AGENTS.md` and `docs/agent-context/`) +- [ ] Public API changes are documented +- [ ] No secrets or credentials included diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a22a553 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,107 @@ +# Contributing to ChainWeaver + +Thank you for your interest in contributing to ChainWeaver! +This guide covers everything you need to get started, whether you are a human contributor or an AI agent. + +For AI contributors: also read [`AGENTS.md`](AGENTS.md) and [`docs/agent-context/`](docs/agent-context/), which contain agent-specific conventions. `.github/copilot-instructions.md` is a thin wrapper that points to the same sources. + +--- + +## Table of Contents + +- [Dev environment setup](#dev-environment-setup) +- [Running tests](#running-tests) +- [Code style](#code-style) +- [PR process](#pr-process) +- [Reporting issues](#reporting-issues) + +--- + +## Dev environment setup + +```bash +# Clone the repository +git clone https://github.com/dgenio/ChainWeaver.git +cd ChainWeaver + +# Install with dev dependencies (editable mode) +pip install -e ".[dev]" +``` + +Python 3.10 or later is required. + +--- + +## Running tests + +Run the full test suite: + +```bash +pytest tests/ -v +``` + +Run all four validation commands before every commit: + +```bash +ruff check chainweaver/ tests/ examples/ +ruff format --check chainweaver/ tests/ examples/ +python -m mypy chainweaver/ +python -m pytest tests/ -v +``` + +CI runs lint + format + mypy on Python 3.10, and tests across Python 3.10–3.13. + +--- + +## Code style + +- **Type annotations are required** on all function signatures. +- **Pydantic `BaseModel`** for all data schemas (tool I/O, `Flow`, `FlowStep`). +- `from __future__ import annotations` at the top of every module. +- Single runtime dependency: `pydantic>=2.0`. Add new runtime dependencies only when strictly necessary. +- All public symbols must be exported in `chainweaver/__init__.py` `__all__`. +- All exceptions must inherit from `ChainWeaverError`. +- Ruff is the linter and formatter — run `ruff check` and `ruff format --check` before committing. + +### Vocabulary + +Use the canonical terms consistently in code, docs, and PR descriptions: + +| Use | Never use | +|-----|-----------| +| **flow** | chain, pipeline | +| **tool** | function, action (when referring to a `Tool` instance) | + +--- + +## PR process + +1. **One logical change per PR.** Split unrelated changes into separate PRs. +2. **Link the relevant issue** in your PR description under _Related Issues_. +3. **All tests must pass** before requesting review. +4. **Branch naming:** `{type}/{issue_number}-{short-description}` + - Types: `feat`, `fix`, `docs`, `test`, `refactor` + - Example: `feat/55-add-pr-template` +5. **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/): + ``` + feat: add timeout guardrails to tool execution + fix: correct input mapping for literal constants + docs: update architecture map after log_utils rename + ``` +6. Fill in all sections of the PR template (Summary, Changes, Testing, Related Issues, Checklist). +7. Do not include secrets, API keys, credentials, or PII in code, logs, or tests. + +--- + +## Reporting issues + +Use the GitHub issue forms: + +- **Bug report** — unexpected behavior, errors, or incorrect output. +- **Feature request** — new capabilities or enhancements. + +Provide as much context as possible: Python version, ChainWeaver version, a minimal reproduction, and the full traceback where relevant. + +--- + +For the full set of agent-oriented conventions, invariants, and architecture decisions, see [`AGENTS.md`](AGENTS.md) and [`docs/agent-context/`](docs/agent-context/). From 8feb5601fbdc0ed2eaec74ff891f324cf92cf7ef Mon Sep 17 00:00:00 2001 From: Diogo Andre Santos Date: Tue, 14 Apr 2026 05:51:49 +0100 Subject: [PATCH 3/4] docs: align validation commands with canonical workflows.md invocations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CONTRIBUTING.md: change bare \pytest tests/ -v\ to \python -m pytest tests/ -v\ in the quick-start block (workflows.md Command-selection rules require python -m prefix) - .github/pull_request_template.md: add missing \ uff format --check\ step and use canonical scoped invocations (chainweaver/ tests/ examples/) for all four validation commands; replace bare \pytest\/\mypy\ with \python -m\ forms - tests/test_flow_execution.py: fix pre-existing Python 3.14 compatibility break — ZeroDivisionError message shortened from 'integer division or modulo by zero' to 'division by zero'; use any() to handle both Python versions --- .github/pull_request_template.md | 7 ++++--- CONTRIBUTING.md | 2 +- tests/test_flow_execution.py | 7 ++++++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7aa7284..9d728ea 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,10 +7,11 @@ ## Testing -- [ ] All existing tests pass (`pytest`) +- [ ] Linting passes (`ruff check chainweaver/ tests/ examples/`) +- [ ] Formatting check passes (`ruff format --check chainweaver/ tests/ examples/`) +- [ ] Type checking passes (`python -m mypy chainweaver/`) +- [ ] All existing tests pass (`python -m pytest tests/ -v`) - [ ] New tests added for new functionality -- [ ] Linting passes (`ruff check`) -- [ ] Type checking passes (`mypy`) ## Related Issues diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a22a553..4413c42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,7 +37,7 @@ Python 3.10 or later is required. Run the full test suite: ```bash -pytest tests/ -v +python -m pytest tests/ -v ``` Run all four validation commands before every commit: diff --git a/tests/test_flow_execution.py b/tests/test_flow_execution.py index f3e4c26..4088a0b 100644 --- a/tests/test_flow_execution.py +++ b/tests/test_flow_execution.py @@ -680,7 +680,12 @@ def divide_fn(inp: DivInput) -> dict: record = result.execution_log[0] assert record.success is False assert isinstance(record.error, FlowExecutionError) - assert "integer division or modulo by zero" in str(record.error) + # Python <=3.13: "integer division or modulo by zero" + # Python >=3.14: "division by zero" + assert any( + msg in str(record.error) + for msg in ("integer division or modulo by zero", "division by zero") + ) # --------------------------------------------------------------------------- From e4b024905f5ba1b278e508518e87798d000f0830 Mon Sep 17 00:00:00 2001 From: Diogo Andre Santos Date: Tue, 14 Apr 2026 05:58:53 +0100 Subject: [PATCH 4/4] docs: align CONTRIBUTING.md with AGENTS.md and maintainer policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Dep policy: replace 'only when strictly necessary' with 'judiciously — only when they deliver clear value and are well-maintained' to match AGENTS.md §1 and maintainer preference (deps are welcome with justification) - PR process: replace 'Split unrelated changes into separate PRs' with the nuanced AGENTS.md inv. 12 wording — a feature + tests + docs is one logical change; only split if genuinely unrelated - Dev setup: add python -m venv .venv step before pip install to prevent accidental global installs by new contributors --- CONTRIBUTING.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4413c42..d877ef4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,13 @@ For AI contributors: also read [`AGENTS.md`](AGENTS.md) and [`docs/agent-context git clone https://github.com/dgenio/ChainWeaver.git cd ChainWeaver +# Create a virtual environment +python -m venv .venv +# Windows +.venv\Scripts\activate +# Linux/macOS +# source .venv/bin/activate + # Install with dev dependencies (editable mode) pip install -e ".[dev]" ``` @@ -58,7 +65,7 @@ CI runs lint + format + mypy on Python 3.10, and tests across Python 3.10–3.13 - **Type annotations are required** on all function signatures. - **Pydantic `BaseModel`** for all data schemas (tool I/O, `Flow`, `FlowStep`). - `from __future__ import annotations` at the top of every module. -- Single runtime dependency: `pydantic>=2.0`. Add new runtime dependencies only when strictly necessary. +- Single runtime dependency: `pydantic>=2.0`. Add new runtime dependencies judiciously — only when they deliver clear value and are well-maintained. Always update `pyproject.toml` `[project.dependencies]`. - All public symbols must be exported in `chainweaver/__init__.py` `__all__`. - All exceptions must inherit from `ChainWeaverError`. - Ruff is the linter and formatter — run `ruff check` and `ruff format --check` before committing. @@ -76,7 +83,7 @@ Use the canonical terms consistently in code, docs, and PR descriptions: ## PR process -1. **One logical change per PR.** Split unrelated changes into separate PRs. +1. **One logical change per PR.** A PR that implements a feature, adds tests, and updates docs is one logical change. Only split if changes are genuinely unrelated. 2. **Link the relevant issue** in your PR description under _Related Issues_. 3. **All tests must pass** before requesting review. 4. **Branch naming:** `{type}/{issue_number}-{short-description}`