|
1 | 1 | # Contributing to Coding Agent Framework |
2 | 2 |
|
3 | | -Thank you for your interest in contributing! This document outlines the process for contributing to this project. |
4 | | - |
5 | | -## 🚀 Getting Started |
6 | | - |
7 | | -1. **Fork the repository** on GitHub |
8 | | -2. **Clone your fork** locally: |
9 | | - ```bash |
10 | | - git clone https://github.com/YOUR_USERNAME/coding-agent-framework.git |
11 | | - cd coding-agent-framework |
12 | | - ``` |
13 | | -3. **Create a virtual environment** and install dependencies: |
14 | | - ```bash |
15 | | - python -m venv .venv |
16 | | - source .venv/bin/activate # Windows: .venv\Scripts\activate |
17 | | - pip install -e .[dev] |
18 | | - ``` |
19 | | -4. **Run tests** to verify setup: |
20 | | - ```bash |
21 | | - pytest tests/ -v |
22 | | - ``` |
23 | | - |
24 | | -## 📋 Development Workflow |
25 | | - |
26 | | -### Branch Naming Convention |
27 | | - |
28 | | -| Type | Prefix | Example | |
29 | | -|------|--------|---------| |
30 | | -| Feature | `feat/` | `feat/add-azure-openai-support` | |
31 | | -| Bug Fix | `fix/` | `fix/sandbox-timeout-windows` | |
32 | | -| Documentation | `docs/` | `docs/update-api-reference` | |
33 | | -| Refactor | `refactor/` | `refactor/llm-factory-pattern` | |
34 | | -| Test | `test/` | `test/integration-pipeline` | |
35 | | -| Chore | `chore/` | `chore/update-dependencies` | |
36 | | - |
37 | | -### Commit Message Format |
38 | | - |
39 | | -We follow [Conventional Commits](https://www.conventionalcommits.org/): |
| 3 | +Thank you for your interest in contributing! Contributions are what make the open-source community a great place to learn and grow. |
40 | 4 |
|
41 | | -``` |
42 | | -<type>(<scope>): <short summary> |
43 | | -
|
44 | | -<body> |
45 | | -
|
46 | | -<footer> |
47 | | -``` |
48 | | - |
49 | | -**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci` |
| 5 | +## How to Contribute |
50 | 6 |
|
51 | | -**Examples:** |
52 | | -``` |
53 | | -feat(llm): add support for Azure OpenAI managed identity auth |
54 | | -
|
55 | | -fix(sandbox): handle resource limits on Windows platform |
56 | | -
|
57 | | -docs(readme): add WebSocket streaming example |
58 | | -``` |
| 7 | +### Reporting Bugs |
59 | 8 |
|
60 | | -### Pull Request Process |
| 9 | +1. Check [existing issues](https://github.com/DavidEscotoDev/Framework/issues) first. |
| 10 | +2. Open a bug report with a clear title and description. |
| 11 | +3. Include reproduction steps, expected vs. actual behavior, and your environment. |
61 | 12 |
|
62 | | -1. **Open a draft PR** early for discussion |
63 | | -2. **Ensure all checks pass**: |
64 | | - - `ruff check .` (linting) |
65 | | - - `ruff format .` (formatting) |
66 | | - - `mypy src/coding_agent --ignore-missing-imports` (type checking) |
67 | | - - `pytest tests/ -v` (tests) |
68 | | -3. **Update documentation** if needed |
69 | | -4. **Request review** from maintainers |
70 | | -5. **Address feedback** and push updates |
71 | | -6. **Squash and merge** when approved |
| 13 | +### Suggesting Features |
72 | 14 |
|
73 | | -## 🧪 Testing Guidelines |
| 15 | +1. Check existing feature requests first. |
| 16 | +2. Open a feature request explaining the use case and expected behavior. |
74 | 17 |
|
75 | | -### Writing Tests |
| 18 | +### Pull Requests |
76 | 19 |
|
77 | | -- **Unit tests**: Test individual functions/classes in isolation with mocks |
78 | | -- **Integration tests**: Test full pipeline with mocked LLM providers |
79 | | -- **Location**: `tests/unit/` or `tests/integration/` |
80 | | -- **Naming**: `test_<module>_<functionality>.py` |
| 20 | +1. Fork the repository. |
| 21 | +2. Create a feature branch (`git checkout -b feature/amazing-feature`). |
| 22 | +3. Make your changes. |
| 23 | +4. Run tests and linting (see below). |
| 24 | +5. Commit with a conventional message (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`). |
| 25 | +6. Push and open a Pull Request. |
81 | 26 |
|
82 | | -### Test Fixtures |
| 27 | +## Development Setup |
83 | 28 |
|
84 | | -Use the existing fixtures in `tests/conftest.py`: |
85 | | -- `mock_llm_response` - Standard LLM response |
86 | | -- `mock_llm_provider` - AsyncMock with health_check and estimate_cost |
87 | | - |
88 | | -### Adding New Tests |
89 | | - |
90 | | -```python |
91 | | -# tests/unit/test_new_feature.py |
92 | | -import pytest |
93 | | -from coding_agent.module import NewFeature |
| 29 | +```bash |
| 30 | +git clone https://github.com/DavidEscotoDev/Framework.git |
| 31 | +cd Framework |
| 32 | +pip install -e ".[dev]" |
| 33 | +``` |
94 | 34 |
|
95 | | -def test_new_feature_basic(): |
96 | | - feature = NewFeature() |
97 | | - assert feature.do_something() == expected_result |
| 35 | +## Code Style |
98 | 36 |
|
99 | | -@pytest.mark.asyncio |
100 | | -async def test_new_feature_async(mock_llm_provider): |
101 | | - # Integration-style test |
102 | | - pass |
103 | | -``` |
| 37 | +- Linted with [ruff](https://github.com/astral-sh/ruff). |
| 38 | +- Format: `ruff format .` |
| 39 | +- Type-check: `mypy .` |
| 40 | +- Tests: `pytest` |
104 | 41 |
|
105 | | -## 🎨 Code Style |
| 42 | +## Testing |
106 | 43 |
|
107 | | -We use **Ruff** for linting and formatting (replaces Black, isort, flake8): |
| 44 | +Run the full suite before opening a PR: |
108 | 45 |
|
109 | 46 | ```bash |
110 | | -# Check |
111 | 47 | ruff check . |
112 | | - |
113 | | -# Auto-fix |
114 | | -ruff check --fix . |
115 | | - |
116 | | -# Format |
117 | | -ruff format . |
| 48 | +pytest tests/ -v |
118 | 49 | ``` |
119 | 50 |
|
120 | | -**Key rules:** |
121 | | -- Line length: 100 characters |
122 | | -- Target: Python 3.11+ |
123 | | -- Import sorting: isort-compatible |
124 | | -- Type hints required for public APIs |
125 | | - |
126 | | -### Type Hints |
127 | | - |
128 | | -- Use `X | None` instead of `Optional[X]` (Python 3.10+) |
129 | | -- Annotate all public function signatures |
130 | | -- Use `TypedDict` for dictionary shapes |
131 | | -- Prefer `list[str]` over `List[str]` (Python 3.9+) |
132 | | - |
133 | | -## 📝 Documentation |
134 | | - |
135 | | -- **Docstrings**: Google-style for all public classes/functions |
136 | | -- **README**: Update for new features, CLI commands, config options |
137 | | -- **API Reference**: Update `docs/api_reference.md` for new endpoints |
138 | | -- **Architecture**: Update `docs/architecture.md` for structural changes |
139 | | - |
140 | | -## 🐛 Reporting Bugs |
141 | | - |
142 | | -Use the [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.yml) with: |
143 | | -- Python version (`python --version`) |
144 | | -- OS and version |
145 | | -- Steps to reproduce |
146 | | -- Expected vs actual behavior |
147 | | -- Relevant logs/config (sanitized) |
148 | | - |
149 | | -## 💡 Feature Requests |
150 | | - |
151 | | -Use the [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.yml) with: |
152 | | -- Problem statement |
153 | | -- Proposed solution |
154 | | -- Alternatives considered |
155 | | -- Implementation approach (if known) |
156 | | - |
157 | | -## 🔒 Security Issues |
158 | | - |
159 | | -**Do not open public issues** for security vulnerabilities. Email security@yourdomain.com or use GitHub Security Advisories. |
160 | | - |
161 | | ---- |
162 | | - |
163 | | -## 🏷 Release Process |
164 | | - |
165 | | -Maintainers only: |
166 | | -1. Update `CHANGELOG.md` |
167 | | -2. Bump version in `pyproject.toml` |
168 | | -3. Create git tag: `git tag v0.x.x` |
169 | | -4. Push tag: `git push origin v0.x.x` |
170 | | -5. GitHub Actions builds and publishes to PyPI |
171 | | - |
172 | | ---- |
173 | | - |
174 | | -## 📞 Getting Help |
175 | | - |
176 | | -- **Discussions**: GitHub Discussions for questions |
177 | | -- **Issues**: Bug reports and feature requests |
178 | | -- **Discord**: [Community Server](https://discord.gg/example) (if available) |
179 | | - |
180 | | ---- |
| 51 | +## License |
181 | 52 |
|
182 | | -Thank you for contributing! 🎉 |
| 53 | +By contributing, you agree that your contributions will be licensed under the project's MIT License. |
0 commit comments