|
1 | 1 | # Contributing to PyCDP |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! We welcome contributions from the community. |
| 3 | +Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! This document provides guidelines for contributing to the project. |
4 | 4 |
|
5 | | -## Getting Started |
| 5 | +## Code of Conduct |
6 | 6 |
|
7 | | -### Prerequisites |
| 7 | +By participating in this project, you agree to abide by our Code of Conduct (see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)). |
8 | 8 |
|
9 | | -- Python 3.7 or higher |
10 | | -- Poetry for dependency management |
11 | | -- Git for version control |
| 9 | +## How to Contribute |
12 | 10 |
|
13 | | -### Setting Up Development Environment |
| 11 | +### Reporting Bugs |
14 | 12 |
|
15 | | -1. Fork and clone the repository: |
16 | | - ```bash |
17 | | - git clone https://github.com/YOUR_USERNAME/python-chrome-devtools-protocol.git |
18 | | - cd python-chrome-devtools-protocol |
19 | | - ``` |
| 13 | +If you find a bug, please open an issue on GitHub with: |
| 14 | +- A clear description of the problem |
| 15 | +- Steps to reproduce the issue |
| 16 | +- Expected vs. actual behavior |
| 17 | +- Your environment (OS, Python version, etc.) |
20 | 18 |
|
21 | | -2. Install dependencies: |
| 19 | +### Suggesting Enhancements |
| 20 | + |
| 21 | +Enhancement suggestions are welcome! Please open an issue describing: |
| 22 | +- The enhancement you'd like to see |
| 23 | +- Why it would be useful |
| 24 | +- Any implementation ideas you have |
| 25 | + |
| 26 | +### Pull Requests |
| 27 | + |
| 28 | +1. **Fork the repository** and create your branch from `master` |
| 29 | +2. **Install development dependencies**: |
22 | 30 | ```bash |
23 | 31 | pip install poetry |
24 | 32 | poetry install |
25 | 33 | ``` |
| 34 | +3. **Make your changes** following the project's coding standards |
| 35 | +4. **Run tests** to ensure nothing is broken: |
| 36 | + ```bash |
| 37 | + poetry run make |
| 38 | + ``` |
| 39 | +5. **Update documentation** if needed |
| 40 | +6. **Commit your changes** with clear, descriptive commit messages |
| 41 | +7. **Push to your fork** and submit a pull request |
26 | 42 |
|
27 | | -## Development Workflow |
| 43 | +## Development Setup |
28 | 44 |
|
29 | | -### Code Generation |
| 45 | +### Prerequisites |
| 46 | + |
| 47 | +- Python 3.7 or higher |
| 48 | +- Poetry for dependency management |
30 | 49 |
|
31 | | -This project automatically generates Python wrappers from the Chrome DevTools Protocol specification: |
| 50 | +### Installation |
32 | 51 |
|
33 | 52 | ```bash |
34 | | -poetry run python generator/generate.py |
| 53 | +# Clone the repository |
| 54 | +git clone https://github.com/HyperionGray/python-chrome-devtools-protocol.git |
| 55 | +cd python-chrome-devtools-protocol |
| 56 | + |
| 57 | +# Install dependencies |
| 58 | +poetry install |
35 | 59 | ``` |
36 | 60 |
|
37 | 61 | ### Running Tests |
38 | 62 |
|
39 | | -Run the test suite: |
40 | 63 | ```bash |
| 64 | +# Run all tests |
| 65 | +poetry run make |
| 66 | + |
| 67 | +# Run specific test suites |
41 | 68 | poetry run pytest test/ |
42 | 69 | poetry run pytest generator/ |
43 | | -``` |
44 | | - |
45 | | -### Type Checking |
46 | 70 |
|
47 | | -We use mypy for static type checking: |
48 | | -```bash |
| 71 | +# Run type checking |
49 | 72 | poetry run mypy cdp/ |
50 | 73 | poetry run mypy generator/ |
51 | 74 | ``` |
52 | 75 |
|
53 | | -### Complete Build |
| 76 | +### Code Generation |
| 77 | + |
| 78 | +This project generates Python code from the Chrome DevTools Protocol specification: |
54 | 79 |
|
55 | | -Run all checks (type checking, tests, and generation): |
56 | 80 | ```bash |
57 | | -poetry run make default |
| 81 | +poetry run python generator/generate.py |
58 | 82 | ``` |
59 | 83 |
|
60 | | -## Submitting Changes |
61 | | - |
62 | | -### Pull Request Process |
63 | | - |
64 | | -1. Create a new branch for your feature or bugfix: |
65 | | - ```bash |
66 | | - git checkout -b feature/your-feature-name |
67 | | - ``` |
68 | | - |
69 | | -2. Make your changes and ensure: |
70 | | - - All tests pass |
71 | | - - Code passes type checking |
72 | | - - Code follows the existing style |
73 | | - - Documentation is updated if needed |
74 | | - |
75 | | -3. Commit your changes with clear, descriptive messages: |
76 | | - ```bash |
77 | | - git commit -m "Add feature: brief description" |
78 | | - ``` |
79 | | - |
80 | | -4. Push to your fork and submit a pull request: |
81 | | - ```bash |
82 | | - git push origin feature/your-feature-name |
83 | | - ``` |
84 | | - |
85 | | -5. In your pull request description: |
86 | | - - Describe what changes you made and why |
87 | | - - Reference any related issues |
88 | | - - Include any relevant context |
89 | | - |
90 | | -### Code Review |
91 | | - |
92 | | -- Maintainers will review your pull request |
93 | | -- Address any feedback or requested changes |
94 | | -- Once approved, a maintainer will merge your PR |
95 | | - |
96 | | -## Reporting Issues |
97 | | - |
98 | | -### Bug Reports |
99 | | - |
100 | | -When reporting bugs, please include: |
101 | | -- A clear, descriptive title |
102 | | -- Steps to reproduce the issue |
103 | | -- Expected behavior vs. actual behavior |
104 | | -- Python version and environment details |
105 | | -- Any relevant error messages or logs |
| 84 | +The generated code is checked into version control. If you modify the generator, run it and include the updated generated files in your PR. |
106 | 85 |
|
107 | | -### Feature Requests |
| 86 | +## Coding Standards |
108 | 87 |
|
109 | | -For feature requests, please: |
110 | | -- Clearly describe the feature and its use case |
111 | | -- Explain why it would be valuable |
112 | | -- Provide examples if possible |
| 88 | +- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines |
| 89 | +- Use type hints for all functions and methods |
| 90 | +- Write docstrings for public APIs |
| 91 | +- Ensure code passes `mypy` type checking |
| 92 | +- Keep code coverage high |
113 | 93 |
|
114 | | -## Code Style |
| 94 | +## Project Structure |
115 | 95 |
|
116 | | -- Follow PEP 8 style guidelines |
117 | | -- Use type hints for function parameters and return values |
118 | | -- Write clear, descriptive variable and function names |
119 | | -- Add docstrings for public APIs |
120 | | -- Keep functions focused and modular |
| 96 | +- `cdp/` - Generated CDP protocol bindings |
| 97 | +- `generator/` - Code generator for CDP bindings |
| 98 | +- `test/` - Test suite |
| 99 | +- `docs/` - Documentation source files |
| 100 | +- `examples/` - Example usage scripts |
121 | 101 |
|
122 | | -## Documentation |
| 102 | +## Questions? |
123 | 103 |
|
124 | | -- Update README.md if you add new features |
125 | | -- Update docstrings for any modified functions or classes |
126 | | -- Add examples for new functionality when appropriate |
| 104 | +If you have questions about contributing, feel free to open an issue or reach out to the maintainers. |
127 | 105 |
|
128 | 106 | ## License |
129 | 107 |
|
130 | | -By contributing, you agree that your contributions will be licensed under the MIT License. |
131 | | - |
132 | | -## Questions? |
133 | | - |
134 | | -If you have questions, feel free to: |
135 | | -- Open an issue for discussion |
136 | | -- Reach out to the maintainers |
137 | | - |
138 | | -Thank you for contributing to PyCDP! |
| 108 | +By contributing to PyCDP, you agree that your contributions will be licensed under the MIT License. |
0 commit comments