alishahryar1--free-claude-code
Ali Khokhar
3c9d0ced76
## Problem The README mixed customer setup with provider internals and contributor guidance, making installation and everyday usage harder to scan. ## Changes | Before | After | | --- | --- | | Customer setup was spread across a 725-line README. | Customer setup follows a clear install, configure, run, connect, and manage flow. | | Providers used long implementation-oriented sections. | All 24 providers use a compact configuration table with essential notes. | | Secondary clients and integrations filled the main scan path. | Secondary clients and integrations use collapsible usage guides. | | Development and contribution guidance lived in the customer README. | Contributor guidance lives in `CONTRIBUTING.md`, with architecture linked separately. | | Internal capabilities were classified as README claims. | Internal capabilities are classified as public-surface coverage and provider documentation is contract-tested. | | README simplification risked removing project identity and social proof. | Existing badges, screenshot gallery, and Star History remain. | <!-- greptile_comment --> <details open><summary><h3>Greptile Summary</h3></summary> This PR simplifies the customer README and moves contributor guidance into a dedicated file. The main changes are: - Shorter Quick Start, provider, client, integration, and management sections in `README.md`. - New `CONTRIBUTING.md` with setup, checks, standards, and versioning guidance. - Feature coverage reclassified from README claims to public-surface coverage. - A contract test for keeping the README provider table aligned with the provider catalog. </details> <h3>Confidence Score: 5/5</h3> This looks safe to merge. No blocking issues found in the changed code. No files need attention. <details><summary><h3><a href="https://www.greptile.com/trex"><img alt="T-Rex" src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg" height="20" align="absmiddle"></a> T-Rex Logs</h3></summary> **What T-Rex did** - Ran the Pytest-based docs contract checks and captured a log that records the Pytest command, working directory, output, and exit code 0. - Ran the Ruff-based docs contract validation and captured a log that records the Ruff command, working directory, output, and exit code 0. <a href="https://app.greptile.com/trex/runs/13926440/artifacts"><picture><source media="(prefers-color-scheme: dark)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifactsDark.svg?v=4"><source media="(prefers-color-scheme: light)" srcset="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"><img alt="View all artifacts" src="https://greptile-static-assets.s3.amazonaws.com/badges/ViewAllArtifacts.svg?v=4"></picture></a> <sub><a href="https://www.greptile.com/trex"><img alt="T-Rex" src="https://greptile-static-assets.s3.amazonaws.com/trex/trex_green.svg" height="14" align="absmiddle"></a> Ran code and verified through T-Rex</sub> </details> <details open><summary><h3>Important Files Changed</h3></summary> | Filename | Overview | |----------|----------| | README.md | Reworked the README into a shorter customer setup and usage guide. | | CONTRIBUTING.md | Added contributor setup, quality checks, project standards, and versioning guidance. | | smoke/features.py | Moved several feature entries from README coverage to public-surface coverage. | | tests/contracts/test_feature_manifest.py | Added a provider table contract test against the provider catalog. | </details> <sub>Reviews (1): Last reviewed commit: ["Simplify README around customer usage"](https://github.com/alishahryar1/free-claude-code/commit/ba0a7a837417b1566f071373d71ae14ecadfe5e7) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=43185730)</sub> <!-- /greptile_comment -->
64 行
2.5 KiB
Markdown
64 行
2.5 KiB
Markdown
# 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](ARCHITECTURE.md) before changing package boundaries, providers, protocol conversion, launchers, or messaging.
|
|
|
|
## Development Setup
|
|
|
|
Install [uv](https://docs.astral.sh/uv/) and Python 3.14, then run directly from the checkout:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./scripts/ci.sh
|
|
```
|
|
|
|
```powershell
|
|
.\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:
|
|
|
|
```bash
|
|
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](ARCHITECTURE.md) for extension checklists and the full system design.
|