Skip to content

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

MSeal
Copy link
Contributor

@MSeal MSeal commented Jun 13, 2025

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

  • Contains customer facing changes? Including API/behavior changes
  • Did you add sufficient unit test and/or integration test coverage for this PR?
    • If not, please explain why it is not required
    • Documentation change only, no behavior or code differences

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.

@MSeal MSeal self-assigned this Jun 13, 2025
@Copilot Copilot AI review requested due to automatic review settings June 13, 2025 23:48
@MSeal MSeal requested review from a team as code owners June 13, 2025 23:48
@MSeal MSeal added the docs Requesting a documentation change label Jun 13, 2025
@confluent-cla-assistant
Copy link

🎉 All Contributor License Agreements have been signed. Ready to merge.
Please push an empty commit if you would like to re-run the checks to verify CLA status for all contributors.

Copy link

@Copilot Copilot AI left a 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 of python3

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 using python3 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)

@sonarqube-confluent
Copy link

Passed

Analysis Details

0 Issues

  • Bug 0 Bugs
  • Vulnerability 0 Vulnerabilities
  • Code Smell 0 Code Smells

Coverage and Duplications

  • Coverage No coverage information (66.00% Estimated after merge)
  • Duplications No duplication information (5.20% Estimated after merge)

Project ID: confluent-kafka-python

View in SonarQube

Copy link
Member

@pranavrth pranavrth left a 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
Copy link
Member

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`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Private Methods**: Prefix with single underscore `_private_method`
- **Private Objects**: Prefix with single underscore `_private_method`

Comment on lines +116 to +126
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
```
Copy link
Member

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
Copy link
Member

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**
Copy link
Member

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
Copy link
Member

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]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)
Copy link
Member

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
Copy link
Member

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.

  1. python - There is no installation candidate for 'python' package.
  2. python-pip - Installs pip for python2
  3. python-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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Requesting a documentation change
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy