Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (72 loc) · 3.12 KB

CONTRIBUTING.md

File metadata and controls

100 lines (72 loc) · 3.12 KB
Raw

Contributing to ScholarAIO

Thanks for your interest in contributing! This document explains how to get involved.

Development Setup

# Clone and install
git clone https://github.com/zimoliao/scholaraio.git
cd scholaraio
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

Two Ways to Contribute

1. Orchestration Skills (no Python needed)

Skills in .claude/skills/ are pure-prompt definitions that combine existing CLI commands. To add one:

  1. Create .claude/skills/<name>/SKILL.md with YAML frontmatter + instructions
  2. Follow the AgentSkills.io format
  3. Test with Claude Code: /<name>

See existing skills (e.g., literature-review, writing-polish) for examples.

2. Core Features (Python + CLI)

For new functionality that requires code:

  1. Implement in scholaraio/ (library module)
  2. Expose via cli.py (CLI subcommand)
  3. Add contract-level tests in tests/
  4. Optionally create a skill in .claude/skills/

Pull Request Process

  1. Fork the repo and create a branch from main
  2. Make your changes
  3. Ensure all checks pass: 
    ruff check scholaraio/       # lint
ruff format --check scholaraio/  # format
mypy scholaraio/              # type check
pytest                        # tests
  4. Submit a PR with a clear description

Commit Messages

We use Conventional Commits:

  • feat: — new feature
  • fix: — bug fix
  • docs: — documentation only
  • refactor: — code change that neither fixes a bug nor adds a feature
  • test: — adding or updating tests
  • chore: — maintenance (CI, deps, config)

Test Guidelines

  • Test behavior contracts, not implementation details
  • A refactor should not break tests — if it does, the test was too coupled
  • Use tmp_path / tmp_papers fixtures for isolation
  • Mark slow tests (network, GPU) with @pytest.mark.slow

Code Style

  • Linter/formatter: ruff (configured in pyproject.toml)
  • Type hints: encouraged, checked by mypy with ignore_missing_imports
  • Docstrings: Google-style for public API functions in library modules
  • CLI handlers (cmd_* in cli.py): no docstrings needed
  • UI text (CLI output, help, errors): Chinese
  • Code comments: English, only when logic isn't self-evident

Project Structure

Directory Purpose
scholaraio/ Python package (library + CLI)
.claude/skills/ Agent skill definitions (SKILL.md)
tests/ Contract-level test suite
data/ User paper library (not tracked)
workspace/ User workspace outputs (not tracked)
docs/ Documentation

Reporting Issues

Questions?

Open a discussion or file an issue.