alishahryar1--free-claude-code/CONTRIBUTING.md

Contributing

Thanks for helping improve Free Claude Code. Keep changes focused, test the behavior you change, and preserve the public Claude Code and Codex workflows.

Before Opening A Pull Request

• Open an issue before proposing README changes.
• Do not open Docker integration pull requests.
• For bugs, include every model mapping, the active model when the failure occurred, the complete error, and reproducible steps.
• Add focused tests for behavior changes and relevant edge cases.
• Read ARCHITECTURE.md before changing package boundaries, providers, protocol conversion, launchers, or messaging.

Development Setup

Install uv and Python 3.14, then run directly from the checkout:

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
uv python install 3.14.0
uv run fcc-server

Use uv run for Python commands. Do not run the project with a global Python interpreter.

Quality Checks

Run the complete local CI sequence before opening a pull request:

./scripts/ci.sh

.\scripts\ci.ps1

Useful iteration flags are --only, --skip, and --dry-run on macOS/Linux, or -Only, -Skip, and -DryRun in PowerShell.

Individual repair and test commands:

uv run ruff format
uv run ruff check --fix
uv run ty check
uv run pytest -v --tb=short

GitHub CI runs Ruff in check-only mode and also bans # type: ignore, # ty: ignore, and legacy annotation workarounds. Fix underlying typing and import-boundary problems instead of suppressing them.

Project Standards

• Target Python 3.14 and rely on native lazy annotations; do not add from __future__ import annotations.
• Python 3.14 supports multiple exception types without parentheses, such as except TypeError, ValueError:.
• Keep shared Anthropic protocol behavior under src/free_claude_code/core/anthropic/ rather than importing utilities from another provider.
• Keep provider-specific configuration in the provider that owns it.
• Remove dead compatibility code when completing migrations unless preserving a published interface is explicitly required.

Versioning

Changes to runtime code, packaging, dependencies, or install/CI scripts require a semantic version bump in pyproject.toml and a matching uv lock update in the same commit. Documentation, tests, smoke coverage, and repository configuration do not require a version bump by themselves.

See ARCHITECTURE.md for extension checklists and the full system design.