|
| 1 | +--- |
| 2 | +type: docs |
| 3 | +title: "Contributing to Dapr agents" |
| 4 | +linkTitle: "Dapr agents" |
| 5 | +weight: 85 |
| 6 | +description: Guidelines for contributing to Dapr agents |
| 7 | +--- |
| 8 | + |
| 9 | +When contributing to Dapr agents, the following rules and best-practices should be followed. |
| 10 | + |
| 11 | +## Examples |
| 12 | + |
| 13 | +The examples directory contains code samples for users to run to try out specific functionality of the various Dapr agents packages and extensions. When writing new and updated samples keep in mind: |
| 14 | + |
| 15 | +- All examples should be runnable on Windows, Linux, and MacOS. While Python code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}}) |
| 16 | +- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine. |
| 17 | + |
| 18 | +## Dependencies |
| 19 | + |
| 20 | +This project uses modern Python packaging with `pyproject.toml`. Dependencies are managed as follows: |
| 21 | + |
| 22 | +- Main dependencies are in `[project.dependencies]` |
| 23 | +- Test dependencies are in `[project.optional-dependencies.test]` |
| 24 | +- Development dependencies are in `[project.optional-dependencies.dev]` |
| 25 | + |
| 26 | +### Generating Requirements Files |
| 27 | + |
| 28 | +If you need to generate requirements files (e.g., for deployment or specific environments): |
| 29 | + |
| 30 | +```bash |
| 31 | +# Generate requirements.txt |
| 32 | +pip-compile pyproject.toml |
| 33 | + |
| 34 | +# Generate dev-requirements.txt |
| 35 | +pip-compile pyproject.toml --extra dev |
| 36 | +``` |
| 37 | + |
| 38 | +### Installing Dependencies |
| 39 | + |
| 40 | +```bash |
| 41 | +# Install main package with test dependencies |
| 42 | +pip install -e ".[test]" |
| 43 | + |
| 44 | +# Install main package with development dependencies |
| 45 | +pip install -e ".[dev]" |
| 46 | + |
| 47 | +# Install main package with all optional dependencies |
| 48 | +pip install -e ".[test,dev]" |
| 49 | +``` |
| 50 | + |
| 51 | +## Testing |
| 52 | + |
| 53 | +The project uses pytest for testing. To run tests: |
| 54 | + |
| 55 | +```bash |
| 56 | +# Run all tests |
| 57 | +tox -e pytest |
| 58 | + |
| 59 | +# Run specific test file |
| 60 | +tox -e pytest tests/test_random_orchestrator.py |
| 61 | + |
| 62 | +# Run tests with coverage |
| 63 | +tox -e pytest --cov=dapr_agents |
| 64 | +``` |
| 65 | + |
| 66 | +## Code Quality |
| 67 | + |
| 68 | +The project uses several tools to maintain code quality: |
| 69 | + |
| 70 | +```bash |
| 71 | +# Run linting |
| 72 | +tox -e flake8 |
| 73 | + |
| 74 | +# Run code formatting |
| 75 | +tox -e ruff |
| 76 | + |
| 77 | +# Run type checking |
| 78 | +tox -e type |
| 79 | +``` |
| 80 | + |
| 81 | +## Development Workflow |
| 82 | + |
| 83 | +1. Install development dependencies: |
| 84 | + ```bash |
| 85 | + pip install -e ".[dev]" |
| 86 | + ``` |
| 87 | + |
| 88 | +2. Run tests before making changes: |
| 89 | + ```bash |
| 90 | + tox -e pytest |
| 91 | + ``` |
| 92 | + |
| 93 | +3. Make your changes |
| 94 | + |
| 95 | +4. Run code quality checks: |
| 96 | + ```bash |
| 97 | + tox -e flake8 |
| 98 | + tox -e ruff |
| 99 | + tox -e type |
| 100 | + ``` |
| 101 | + |
| 102 | +5. Run tests again: |
| 103 | + ```bash |
| 104 | + tox -e pytest |
| 105 | + ``` |
| 106 | + |
| 107 | +6. Submit your changes |
| 108 | + |
| 109 | +## GitHub Dapr Bot Commands |
| 110 | + |
| 111 | +Checkout the [daprbot documentation]({{< ref "daprbot.md" >}}) for GitHub commands you can run in this repo for common tasks. For example, you can run the `/assign` (as a comment on an issue) to assign issues to a user or group of users. |
| 112 | + |
| 113 | +## Feedback |
| 114 | + |
| 115 | +Was this page helpful? |
0 commit comments