Added contributor.md and updated code block styles to better fix github markdown patterns #1997
Conversation
…ub markdown patterns
|
🎉 All Contributor License Agreements have been signed. Ready to merge. |
There was a problem hiding this comment.
Pull Request Overview
This PR adds a new CONTRIBUTOR.md file and standardizes documentation by converting inline command snippets to fenced bash code blocks and unifying Python invocation.
- Adds detailed contributor guidelines in
CONTRIBUTOR.md - Replaces inline shell commands with fenced
bashblocks across docs - Updates instructions to use
pythoninstead ofpython3
Reviewed Changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| tests/README.md | Converted commands to fenced bash blocks and updated Python call |
| examples/docker/README.md | Wrapped Docker build command in fenced bash block |
| examples/README.md | Standardized venv and install commands with fenced bash blocks |
| README.md | Fenced installation commands in bash blocks |
| INSTALL.md | Unified Python invocation and added fenced bash blocks |
| DEVELOPER.md | Added setup section and fenced build/docs/unasync commands |
| CONTRIBUTOR.md | Introduced new contributor guidelines documentation |
Comments suppressed due to low confidence (4)
tests/README.md:17
- Consider specifying "Python 3.x" explicitly instead of just "python", since on some systems
pythonmay point to Python 2 or be unavailable.
A python env suitable for running tests:
INSTALL.md:11
- On environments where
pythondefaults to Python 2 or is not installed, consider usingpython3or adding a note about requiring Python 3.
python -m pip install confluent-kafka
DEVELOPER.md:80
- The code fence here wraps both the
python tools/unasync.pycommand and the explanatory comment. It may improve clarity to separate the two into distinct fenced blocks or move the comment outside the block.
```bash
CONTRIBUTOR.md:27
- Relative link to
../../issuesmay not resolve correctly in GitHub Markdown; consider using an absolute path like/issuesor linking directly to the repository's issues page.
[issues](../../issues)
Analysis Details0 Issues
Coverage and Duplications
Project ID: confluent-kafka-python |
| ### Python Code Style | ||
|
|
||
| - **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 | ||
| - **Type Hints**: Use type hints for new code where applicable |
There was a problem hiding this comment.
We don't have type hinting supported till now. Do we want to go to the mixed route of supporting at some places and not supporting at older ones?
| - **Functions and Variables**: `snake_case` | ||
| - **Classes**: `PascalCase` | ||
| - **Constants**: `UPPER_SNAKE_CASE` | ||
| - **Private Methods**: Prefix with single underscore `_private_method` |
There was a problem hiding this comment.
| - **Private Methods**: Prefix with single underscore `_private_method` | |
| - **Private Objects**: Prefix with single underscore `_private_method` |
| 3. **Test Your Changes** | ||
| ```bash | ||
| # Run tests | ||
| python -m pytest | ||
|
|
||
| # Check code style | ||
| flake8 src/ tests/ | ||
|
|
||
| # Update sync code if you modified async code | ||
| python tools/unasync.py --check | ||
| ``` |
There was a problem hiding this comment.
I think we should link tests/README.md here to avoid duplicating the instructions.
|
|
||
| ```bash | ||
| # Install formatting tools | ||
| pip install isort flake8 mypy |
There was a problem hiding this comment.
We are not using isort or mypy right now. We don't have typing support right now in our repo for now.
| git checkout -b fix/issue-number-description | ||
| ``` | ||
|
|
||
| 2. **Make Your Changes** |
There was a problem hiding this comment.
We should ask the user to update the CHANGELOG.md file as well.
|
|
||
| - Contributors are listed in the project's contributor history | ||
| - Significant contributions may be mentioned in release notes | ||
| - Long-term contributors may be invited to become maintainers |
There was a problem hiding this comment.
Since this is Confluent owned, I don't know if this will be allowed. I think we should check this first.
|
|
||
| 3. **Install Dependencies** | ||
| ```bash | ||
| pip install -e .[dev,test,docs] |
There was a problem hiding this comment.
| pip install -e .[dev,test,docs] | |
| pip install -e .[dev,tests,docs] |
| pip install -e .[dev,test,docs] | ||
| ``` | ||
|
|
||
| 4. **Install librdkafka** (if not already installed) |
There was a problem hiding this comment.
This should be installed before installing confluent-kafka-python
| @@ -72,7 +72,7 @@ python3 -c 'import confluent_kafka; print(confluent_kafka.version())' | |||
|
|
|||
| # Install build tools and Kerberos support. | |||
|
|
|||
| apt install -y wget software-properties-common lsb-release gcc make python3 python3-pip python3-dev libsasl2-modules-gssapi-mit krb5-user | |||
| apt install -y wget software-properties-common lsb-release gcc make python python-pip python-dev libsasl2-modules-gssapi-mit krb5-user | |||
There was a problem hiding this comment.
All 3 packages has problems.
python- There is no installation candidate for 'python' package.python-pip- Installs pip for python2python-dev- There is no installation candidate for 'python-dev' package.
We still need to install python3 related things. Lets revert this change and same for other Linux distributions.
| @@ -33,7 +33,7 @@ than from prebuilt binary wheels, such as when: | |||
|
|
|||
| # Install build tools and Kerberos support. | |||
|
|
|||
| yum install -y python3 python3-pip python3-devel gcc make cyrus-sasl-gssapi krb5-workstation | |||
| yum install -y python python-pip python-devel gcc make cyrus-sasl-gssapi krb5-workstation | |||
There was a problem hiding this comment.
Let's revert this change as these packages are either not present or related to python2. I verified this for Ubuntu but same would be applicable here as well.
Adds contributor markdown and cleans up some of documentation. This is an effort as a precursor to engaging the community for completely.
This adds a Contributor.md file, changes the setup instructions to include virtual environment, removes the python2 vs 3 implication for older OS defaults, changes code references to code blocks, and adds some cross md file references where relevant.
Checklist
References
JIRA:
Test & Review
Open questions / Follow-ups
This had been discussed internally ahead of time, nothing surprising for confluent reviewers should pop up.
Initial changes were drafted with cursor then hand touched and reviewed to ensure intent and quality. Recommended that instructions are clear and no typos or mistakes are present in a read through.