diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f95332b..bfca2fc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,8 +1,8 @@ --- name: Bug report -about: Create a report to help us improve +about: Report a bug to help us improve EvoScientist title: '' -labels: '' +labels: bug assignees: '' type: Bug @@ -13,21 +13,26 @@ A clear and concise description of what the bug is. **To Reproduce** Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error +1. Run `EvoSci ...` +2. Provide input '...' +3. See error **Expected behavior** A clear and concise description of what you expected to happen. -**Screenshots** -If applicable, add screenshots to help explain your problem. +**Error output / logs** +If applicable, paste the relevant terminal output or traceback. + +``` + +``` **System information** - - OS: [e.g. Windows, MacOS, Linux] - - Terminal [e.g. iTerm2, Alacritty, Windows Terminal] - - EvoScientist Version [e.g. 0.0.1] + - OS: [e.g. Ubuntu 22.04, macOS 14.3, Windows 11] + - Python version: [e.g. 3.11.8] + - Terminal: [e.g. iTerm2, Alacritty, Windows Terminal] + - EvoScientist version: [e.g. 0.0.2 — run `EvoSci --version`] + - LLM provider: [e.g. Anthropic, OpenAI, Ollama] **Additional context** 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..878e52b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: EvoSkills — niche features & custom workflows + url: https://github.com/EvoScientist/EvoSkills + about: Want to add a feature that serves a specific use case rather than all users? Contribute it as an EvoSkill instead. + - name: Community Discord + url: https://discord.gg/AZ9ZMXkunY + about: Ask questions, get help, and chat with the community. diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 0000000..3feac05 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,18 @@ +--- +name: Documentation +about: Report missing, incorrect, or unclear documentation +title: '' +labels: documentation +assignees: '' +type: Documentation + +--- + +**What documentation is affected?** +Describe which part of the project needs better docs. + +**What is wrong or missing?** +Describe the issue — is something inaccurate, outdated, hard to follow, or missing entirely? + +**Suggested improvement** +If you have a specific fix or addition in mind, describe it here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index e255ea9..8dec7cb 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,15 +1,18 @@ --- name: Feature request -about: Suggest an idea for this project +about: Suggest an idea for EvoScientist core functionality title: '' -labels: '' +labels: enhancement assignees: '' type: Feature --- +> **Note:** We only accept feature requests for core functionality that benefits the majority of users. +> If your idea is a niche workflow or personal utility, consider contributing it to [EvoSkills](https://github.com/EvoScientist/EvoSkills) instead. + **Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] +A clear and concise description of the problem. Ex. "I'm always frustrated when [...]" **Describe the solution you'd like** A clear and concise description of what you want to happen. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..b6cc2c0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +## Description + + + +## Type of change + + + +- [ ] Bug fix +- [ ] New feature — link issue: # +- [ ] Documentation / examples +- [ ] Test improvement +- [ ] Refactor (no behavior change) + +## Checklist + +- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md) +- [ ] This targets **core functionality** used by the majority of users (niche features belong in [EvoSkills](https://github.com/EvoScientist/EvoSkills)) +- [ ] I have added/updated tests where applicable +- [ ] `uv run ruff check .` passes +- [ ] `uv run pytest` passes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c427117..c4fb92e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,60 @@ # Contributing to EvoScientist -We appreciate your interest and the time you spend helping improve EvoScientist. Please read the following instruction on how to help us. +We appreciate your interest and the time you spend helping improve EvoScientist. Please read the following guidelines before contributing. ## How you can contribute -- Report ideas, bugs, and feature requests: open an issue describing intent, motivation, and high-level impact. Make sure to correctly label the Issue. Use the provided template. -- Propose design changes: use issues or discussion threads to outline the problem, alternatives, and trade-offs before implementing. -- Contribute code or docs: submit PRs that tackle an open issue. They must have a clear rationale and tests where applicable. +- **Report bugs and request features:** open an issue using the provided templates. Make sure to use the correct template and labels. +- **Propose design changes:** use issues or discussion threads to outline the problem, alternatives, and trade-offs before implementing. +- **Contribute code or docs:** submit PRs that address an open issue. They must have a clear rationale and tests where applicable. ## What we are looking for in PRs -We aim to keep the EvoScientist with only core functionality that will be used by majority of users. Therefore PRs should only include: -- Bug fixes / Improvements to existing features -- New features that were proposed in an Issue and agreed with Contributor -- Updating documentation -- Improving test suite with meaningful tests +We aim to keep EvoScientist focused on core functionality that benefits the majority of users. PRs should only include: -If you want to add nice to have or niche feature look at contributing to the [EvoSkills repository](https://github.com/EvoScientist/EvoSkills) +- Bug fixes / improvements to existing features +- New features that were proposed in an issue and agreed upon with maintainers +- Documentation updates and examples +- Meaningful additions to the test suite + +If you want to add a niche or specialized workflow, consider contributing to the [EvoSkills repository](https://github.com/EvoScientist/EvoSkills) instead. + +## Development setup + +1. **Fork and clone** the repository: + ```bash + git clone https://github.com//EvoScientist.git + cd EvoScientist + ``` + +2. **Install dependencies** (requires [uv](https://docs.astral.sh/uv/)): + ```bash + uv sync --dev + ``` + +3. **Run the test suite** (no API keys needed): + ```bash + uv run pytest + ``` + +4. **Run the linter:** + ```bash + uv run ruff check . + ``` + +## Submitting a pull request + +1. Create a branch from `main` with a descriptive name (e.g. `fix/session-crash`, `feat/export-csv`). +2. Make your changes, keeping commits focused and well-described. +3. Ensure `uv run ruff check .` and `uv run pytest` pass locally — these also run in CI. +4. Open a PR against `main` and fill in the PR template. +5. A maintainer will review your PR. Please be responsive to feedback. + +## Code style + +- We use [Ruff](https://docs.astral.sh/ruff/) for linting. Run `uv run ruff check .` before pushing. +- Follow the existing code patterns and conventions in the area you're modifying. +- Keep changes minimal and focused on the task at hand. --- @@ -44,7 +82,7 @@ EvoScientist is a multi-agent AI system for automated scientific experimentation | `data-analysis-agent` | Computes metrics, creates plots, summarizes insights | | `writing-agent` | Drafts paper-ready Markdown experiment reports | -### Data Flow +### Data flow ```txt User Input (CLI / TUI / 10 Channel Integrations) @@ -69,4 +107,5 @@ Stream Events --> Emitter --> Tracker --> State --> Rich Display / TUI --- ## Need help? -You can reach us on Discord or WeChat linked in README + +Reach us on [Discord](https://discord.gg/AZ9ZMXkunY) or WeChat (linked in README). diff --git a/EvoScientist/cli/commands.py b/EvoScientist/cli/commands.py index 56d3cac..1e4b886 100644 --- a/EvoScientist/cli/commands.py +++ b/EvoScientist/cli/commands.py @@ -5,6 +5,7 @@ import os import queue import re from datetime import datetime +from importlib.metadata import version as _pkg_version from pathlib import Path from typing import Any, Optional @@ -874,9 +875,23 @@ def mcp_remove( # ============================================================================= +def _version_callback(value: bool): + if value: + typer.echo(f"EvoScientist {_pkg_version('EvoScientist')}") + raise typer.Exit() + + @app.callback(invoke_without_command=True) def _main_callback( ctx: typer.Context, + version: Optional[bool] = typer.Option( + None, + "-V", + "--version", + callback=_version_callback, + is_eager=True, + help="Show version and exit.", + ), mode: Optional[str] = typer.Option( None, "-m",