Skip to content

Contributing to PyCodeCommenter

Thank you for considering a contribution to PyCodeCommenter. Every bug report, documentation improvement, and code contribution makes the tool better for everyone.

Ways to Contribute

Reporting Bugs

Found something broken? Before opening an issue:

  1. Check existing issues to avoid duplicates.
  2. If it hasn't been reported, open a new issue with:
  3. A clear title describing the problem
  4. The Python version and PyCodeCommenter version you are running
  5. A minimal code snippet that reproduces the bug
  6. The actual output and the expected output

Proposing Enhancements

Have an idea for a new feature?

  1. Open an issue to discuss the idea before starting work. This avoids duplicated effort and helps align on design.
  2. Explain what the feature would do and why it is useful.
  3. If the discussion is positive, you are welcome to open a pull request.

Improving Documentation

Documentation fixes are always welcome — no discussion needed for small corrections. For larger documentation additions (new pages, new sections), open an issue first.

Pull Request Workflow

  1. Fork the repository and create a branch from main:
git checkout -b fix/my-bug-description

  1. Make your changes. See the code style guidelines below.

  2. Add tests if you are adding new functionality. The test suite uses pytest:

pytest

  1. Ensure all tests pass before opening a pull request.

  2. Update documentation if your change affects the public API, CLI flags, or behaviour visible to users. The docs live in the docs/ directory.

  3. Open a pull request against main with a clear description of:

  4. What the change does
  5. Why it is needed
  6. Any relevant issue numbers (e.g. Fixes #42)

Code Style

Tool Usage
black Code formatting — run black . before committing
Google-style docstrings All new functions and classes must have docstrings
Python 3.8+ Do not use syntax or stdlib features introduced after 3.8

Run PyCodeCommenter itself on any new code you write:

pycodecommenter validate <your_file.py>

Validation must pass (no ERRORs) before the pull request will be merged.

Development Setup

# Clone your fork
git clone https://github.com/<your-username>/PyCodeCommenter.git
cd PyCodeCommenter

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run the test suite
pytest

# Run validation on the package itself
pycodecommenter validate PyCodeCommenter/

Dev dependencies (installed by pip install -e ".[dev]"): - pytest >= 7.0 - pytest-cov >= 4.0 - black >= 23.0 - flake8 >= 6.0

Need Help?

Feel free to open a discussion or open an issue if you have any questions. No question is too small.