-
Notifications
You must be signed in to change notification settings - Fork 920
Added contributor.md and updated code block styles to better fix github markdown patterns #1997
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
…ub markdown patterns
🎉 All Contributor License Agreements have been signed. Ready to merge. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
bash
blocks across docs - Updates instructions to use
python
instead 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
python
may point to Python 2 or be unavailable.
A python env suitable for running tests:
INSTALL.md:11
- On environments where
python
defaults to Python 2 or is not installed, consider usingpython3
or 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.py
command 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
../../issues
may not resolve correctly in GitHub Markdown; consider using an absolute path like/issues
or linking directly to the repository's issues page.
[issues](../../issues)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First pass comments.
### 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- **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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.