Skip to content

Commit 3e30757

Browse files
MSealMSeal
authored
Added contributor.md and updated code block styles to better fix github markdown patterns (#1997)
Applied PR feedback Reapply pr feedback Applied PR feedback Addressed more python3 references + review request
1 parent 858e77c commit 3e30757

File tree

7 files changed

+329
-42
lines changed

7 files changed

+329
-42
lines changed

‎CONTRIBUTOR.md‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
# Contributing to confluent-kafka-python
2+
3+
Thank you for your interest in contributing to confluent-kafka-python! This document provides guidelines and best practices for contributing to this project.
4+
5+
## Table of Contents
6+
7+
- [Getting Started](#getting-started)
8+
- [Development Environment Setup](#development-environment-setup)
9+
- [Code Style and Standards](#code-style-and-standards)
10+
- [Testing](#testing)
11+
- [Submitting Changes](#submitting-changes)
12+
- [Reporting Issues](#reporting-issues)
13+
- [Community Guidelines](#community-guidelines)
14+
15+
## Getting Started
16+
17+
### Ways to Contribute
18+
19+
- **Bug Reports**: Report bugs and issues you encounter
20+
- **Feature Requests**: Suggest new features or improvements
21+
- **Code Contributions**: Fix bugs, implement features, or improve documentation
22+
- **Documentation**: Improve existing docs or add new documentation
23+
- **Testing**: Help improve test coverage and quality
24+
25+
### Before You Start
26+
27+
1. Check existing [issues](../../issues) to see if your bug/feature has already been reported
28+
2. For major changes, open an issue first to discuss the proposed changes
29+
3. Fork the repository and create a feature branch for your work
30+
31+
## Development Environment Setup
32+
33+
For complete development environment setup instructions, including prerequisites, virtual environment creation, and dependency installation, see the [Development Environment Setup section in DEVELOPER.md](DEVELOPER.md#development-environment-setup).
34+
35+
## Code Style and Standards
36+
37+
### Python Code Style
38+
39+
- **PEP 8**: Follow [PEP 8](https://pep8.org/) style guidelines as a default, with exceptions captured in the `tox.ini` flake8 rules for modern updates to the recommendations
40+
- **Docstrings**: Use Google-style docstrings for all public functions and classes
41+
42+
### Code Formatting
43+
44+
We use automated tools to maintain consistent code style:
45+
46+
```bash
47+
# Install formatting tools
48+
pip install flake8
49+
50+
# Check style
51+
flake8 src/ tests/
52+
```
53+
54+
### Naming Conventions
55+
56+
- **Functions and Variables**: `snake_case`
57+
- **Classes**: `PascalCase`
58+
- **Constants**: `UPPER_SNAKE_CASE`
59+
- **Private Methods/Objects**: Prefix with single underscore `_private_method`
60+
61+
### Documentation
62+
63+
- All public APIs must have docstrings
64+
- Include examples in docstrings when helpful
65+
- Keep docstrings concise but complete
66+
- Update relevant documentation files when making changes
67+
68+
## Testing
69+
70+
### Running Tests
71+
72+
See [tests/README.md](tests/README.md) for comprehensive testing instructions.
73+
74+
### Test Requirements
75+
76+
- **Unit Tests**: All new functionality must include unit tests
77+
- **Integration Tests**: Add integration tests for complex features
78+
- **Test Coverage**: Maintain or improve existing test coverage
79+
- **Test Naming**: Use descriptive test names that explain what is being tested
80+
81+
### Test Structure
82+
83+
```python
84+
def test_feature_should_behave_correctly_when_condition():
85+
# Arrange
86+
setup_data = create_test_data()
87+
88+
# Act
89+
result = function_under_test(setup_data)
90+
91+
# Assert
92+
assert result.expected_property == expected_value
93+
```
94+
95+
## Submitting Changes
96+
97+
### Pull Request Process
98+
99+
1. **Create Feature Branch**
100+
```bash
101+
git checkout -b feature/your-feature-name
102+
# or
103+
git checkout -b fix/issue-number-description
104+
```
105+
106+
2. **Make Your Changes**
107+
- Write clean, well-documented code
108+
- Add appropriate tests
109+
- Update documentation if needed
110+
- Add an entry to the CHANGELOG.md file for the proposed change
111+
112+
3. **Test Your Changes**
113+
Refer to [tests/README.md](tests/README.md)
114+
115+
4. **Commit Your Changes**
116+
```bash
117+
git add .
118+
git commit -m "Clear, descriptive commit message"
119+
```
120+
121+
**Commit Message Guidelines:**
122+
- Use present tense ("Add feature" not "Added feature")
123+
- Keep first line under 50 characters
124+
- Reference issue numbers when applicable (#123)
125+
- Include breaking change notes if applicable
126+
127+
5. **Push and Create Pull Request**
128+
```bash
129+
git push origin feature/your-feature-name
130+
```
131+
132+
Then create a pull request through GitHub's interface.
133+
134+
### Pull Request Guidelines
135+
136+
- **Title**: Clear and descriptive
137+
- **Description**: Explain what changes you made and why
138+
- **Linked Issues**: Reference related issues using "Fixes #123" or "Relates to #123"
139+
- **Labels**: Review available issue/PR labels and apply relevant ones to help with categorization and triage
140+
- **Documentation**: Update documentation for user-facing changes
141+
- **Tests**: Include appropriate tests
142+
- **Breaking Changes**: Clearly mark any breaking changes
143+
144+
### Code Review Process
145+
146+
- All pull requests require review before merging
147+
- Address reviewer feedback promptly
148+
- Keep discussions respectful and constructive
149+
- Be open to suggestions and alternative approaches
150+
151+
## Reporting Issues
152+
153+
### Using Labels
154+
155+
When creating issues or pull requests, please review the available labels and apply those that are relevant to your submission. This helps maintainers categorize and prioritize work effectively. Common label categories include (look at available labels / other issues for options):
156+
157+
- **Type**: bug, enhancement, documentation, question
158+
- **Priority**: high, medium, low
159+
- **Component**: producer, consumer, admin, schema-registry, etc
160+
- **Status**: needs-investigation, help-wanted, good-first-issue, etc
161+
162+
### Bug Reports
163+
164+
When reporting bugs, please include:
165+
166+
- **Clear Title**: Describe the issue concisely
167+
- **Environment**: Python version, OS, library versions
168+
- **Steps to Reproduce**: Detailed steps to reproduce the issue
169+
- **Expected Behavior**: What you expected to happen
170+
- **Actual Behavior**: What actually happened
171+
- **Code Sample**: Minimal code that demonstrates the issue
172+
- **Error Messages**: Full error messages and stack traces
173+
- **Client Configuration**: Specify how the client was configured and setup
174+
- **Logs**: Client logs when possible
175+
- **Labels**: Apply relevant labels such as "bug" and component-specific labels
176+
177+
### Feature Requests
178+
179+
For feature requests, please include:
180+
181+
- **Use Case**: Describe the problem you're trying to solve
182+
- **Proposed Solution**: Your idea for how to address it
183+
- **Alternatives**: Other solutions you've considered
184+
- **Additional Context**: Any other relevant information
185+
- **Labels**: Apply relevant labels such as "enhancement" and component-specific labels
186+
187+
## Community Guidelines
188+
189+
### Code of Conduct
190+
191+
This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/). By participating, you agree to uphold this code.
192+
193+
### Communication
194+
195+
- **Be Respectful**: Treat all community members with respect
196+
- **Be Constructive**: Provide helpful feedback and suggestions
197+
- **Be Patient**: Remember that maintainers and contributors volunteer their time
198+
- **Be Clear**: Communicate clearly and provide sufficient context
199+
200+
### Getting Help
201+
202+
- **Issues**: Use GitHub issues for bug reports and feature requests
203+
- **Discussions**: Use GitHub Discussions for questions and general discussion
204+
- **Documentation**: Check existing documentation before asking questions
205+
206+
## Recognition
207+
208+
Contributors are recognized in the following ways:
209+
210+
- Contributors are listed in the project's contributor history
211+
- Significant contributions may be mentioned in release notes
212+
213+
## License
214+
215+
By contributing to this project, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).
216+
217+
---
218+
219+
Thank you for contributing to confluent-kafka-python! Your contributions help make this project better for everyone.

‎DEVELOPER.md‎

Lines changed: 56 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,41 +2,87 @@
22

33
This document provides information useful to developers working on confluent-kafka-python.
44

5+
## Development Environment Setup
56

6-
## Build
7+
### Prerequisites
78

8-
$ python -m build
9+
- Python 3.7 or higher
10+
- Git
11+
- librdkafka (for Kafka functionality)
912

10-
If librdkafka is installed in a non-standard location provide the include and library directories with:
13+
### Setup Steps
14+
15+
1. **Fork and Clone**
16+
```bash
17+
git clone https://github.com/your-username/confluent-kafka-python.git
18+
cd confluent-kafka-python
19+
```
1120

12-
$ C_INCLUDE_PATH=/path/to/include LIBRARY_PATH=/path/to/lib python -m build
21+
2. **Create Virtual Environment**
22+
```bash
23+
python3 -m venv venv
24+
source venv/bin/activate # On Windows: venv\Scripts\activate
25+
```
1326

1427
**Note**: On Windows the variables for Visual Studio are named INCLUDE and LIB
1528

29+
3. **Install librdkafka** (if not already installed)
30+
See the main README.md for platform-specific installation instructions
31+
32+
If librdkafka is installed in a non-standard location provide the include and library directories with:
33+
34+
```bash
35+
C_INCLUDE_PATH=/path/to/include LIBRARY_PATH=/path/to/lib python -m build
36+
```
37+
38+
4. **Install confluent-kafka-python with optional dependencies**
39+
```bash
40+
pip3 install -e .[dev,tests,docs]
41+
```
42+
43+
This will also build the wheel be default. Alternatively you can build the bundle independently with:
44+
45+
```bash
46+
python3 -m build
47+
```
48+
49+
5. **Verify Setup**
50+
```bash
51+
python3 -c "import confluent_kafka; print('Setup successful!')"
52+
```
53+
1654
## Generate Documentation
1755

1856
Install docs dependencies:
1957

20-
$ pip install .[docs]
58+
```bash
59+
pip3 install .[docs]
60+
```
2161

2262
Build HTML docs:
2363

24-
$ make docs
64+
```bash
65+
make docs
66+
```
2567

2668
Documentation will be generated in `docs/_build/`.
2769

2870
or:
2971

30-
$ python setup.py build_sphinx
72+
```bash
73+
python3 setup.py build_sphinx
74+
```
3175

3276
Documentation will be generated in `build/sphinx/html`.
3377

3478
## Unasync -- maintaining sync versions of async code
3579

36-
$ python tools/unasync.py
80+
```bash
81+
python3 tools/unasync.py
3782

38-
# Run the script with the --check flag to ensure the sync code is up to date
39-
$ python tools/unasync.py --check
83+
# Run the script with the --check flag to ensure the sync code is up to date
84+
python3 tools/unasync.py --check
85+
```
4086

4187
If you make any changes to the async code (in `src/confluent_kafka/schema_registry/_async` and `tests/integration/schema_registry/_async`), you **must** run this script to generate the sync counter parts (in `src/confluent_kafka/schema_registry/_sync` and `tests/integration/schema_registry/_sync`). Otherwise, this script will be run in CI with the --check flag and fail the build.
4288

‎README.md‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,9 @@ The `Producer`, `Consumer` and `AdminClient` are all thread safe.
130130

131131
**Install self-contained binary wheels**
132132

133-
$ pip install confluent-kafka
133+
```bash
134+
pip install confluent-kafka
135+
```
134136

135137
**NOTE:** The pre-built Linux wheels do NOT contain SASL Kerberos/GSSAPI support.
136138
If you need SASL Kerberos/GSSAPI support you must install librdkafka and
@@ -140,19 +142,27 @@ The `Producer`, `Consumer` and `AdminClient` are all thread safe.
140142

141143
To use Schema Registry with the Avro serializer/deserializer:
142144

143-
$ pip install "confluent-kafka[avro,schemaregistry]"
145+
```bash
146+
pip install "confluent-kafka[avro,schemaregistry]"
147+
```
144148

145149
To use Schema Registry with the JSON serializer/deserializer:
146150

147-
$ pip install "confluent-kafka[json,schemaregistry]"
151+
```bash
152+
pip install "confluent-kafka[json,schemaregistry]"
153+
```
148154

149155
To use Schema Registry with the Protobuf serializer/deserializer:
150156

151-
$ pip install "confluent-kafka[protobuf,schemaregistry]"
157+
```bash
158+
pip install "confluent-kafka[protobuf,schemaregistry]"
159+
```
152160

153161
When using Data Contract rules (including CSFLE) add the `rules`extra, e.g.:
154162

155-
$ pip install "confluent-kafka[avro,schemaregistry,rules]"
163+
```bash
164+
pip install "confluent-kafka[avro,schemaregistry,rules]"
165+
```
156166

157167
**Install from source**
158168

‎examples/README.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,26 +27,26 @@ conflicts between projects.
2727

2828
To setup a venv with the latest release version of confluent-kafka and dependencies of all examples installed:
2929

30-
```
31-
$ python3 -m venv venv_examples
32-
$ source venv_examples/bin/activate
33-
$ pip install confluent_kafka
34-
$ pip install -r requirements/requirements-examples.txt
30+
```bash
31+
python3 -m venv venv_examples
32+
source venv_examples/bin/activate
33+
python3 -m pip install confluent_kafka
34+
python3 -m pip install -r requirements/requirements-examples.txt
3535
```
3636

3737
To setup a venv that uses the current source tree version of confluent_kafka, you
3838
need to have a C compiler and librdkafka installed
3939
([from a package](https://github.com/edenhill/librdkafka#installing-prebuilt-packages), or
4040
[from source](https://github.com/edenhill/librdkafka#build-from-source)). Then:
4141

42-
```
43-
$ python3 -m venv venv_examples
44-
$ source venv_examples/bin/activate
45-
$ pip install .[examples]
42+
```bash
43+
python3 -m venv venv_examples
44+
source venv_examples/bin/activate
45+
python3 -m pip install .[examples]
4646
```
4747

4848
When you're finished with the venv:
4949

50-
```
51-
$ deactivate
50+
```bash
51+
deactivate
5252
```

0 commit comments

Comments
 (0)