Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (87 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

131 lines (87 loc) · 3.4 KB
Raw

Contributing to Guard Core

Thank you for considering contributing to Guard Core! This document outlines the process for contributing to this Python library and helps ensure a smooth collaboration experience.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the issue tracker to avoid duplicates. When you create a bug report, include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Provide specific examples (e.g., HTTP requests that trigger the issue)
  • Describe the behavior you observed and why it's problematic
  • Include logs, error messages, and Python version
  • Specify your environment: OS, Python version, framework and version, etc.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide a detailed description of the proposed functionality
  • Explain why this enhancement would be useful to Guard Core users
  • Include examples of how it would be used if applicable
  • List any relevant references or examples from other libraries

Pull Requests

  • Fill in the required template
  • Follow the Python style guides (PEP 8)
  • Include tests for new features or bug fixes
  • Update documentation for significant changes
  • Ensure the test suite passes
  • Make sure your code lints (Mypy, Ruff)

Development Setup

  1. Fork and clone the repository

  2. The project uses Docker for development and testing. Make sure you have Docker and Docker Compose installed on your system.

  3. You can use the provided Makefile commands to set up your development environment:

# Install dependencies using 'uv'
make install

# To stop all containers
make stop

Testing

The project supports Python 3.10, 3.11, 3.12, 3.13 and 3.14. Tests are run using Docker containers:

# Run tests with the default Python version (3.10)
make test

# Run tests with all supported Python versions
make test-all

# Run tests with a specific Python version
make test-3.11

# Run tests locally (if you have 'uv' installed)
make local-test

Style Guidelines

This project uses:

  • Ruff for code formatting and linting
  • mypy for type checking

Before submitting a PR, make sure your code passes all style checks:

make lint
make fix

and

make lint-docs
make fix-docs

Documentation

The documentation for Guard Core is built with MkDocs. To build and view the documentation locally:

make serve-docs

Please update the documentation when making significant changes.

Versioning

This project follows Semantic Versioning.

Release Process

  1. Update version in pyproject.toml and setup.py
  2. Update docs/release-notes.md
  3. Create a new GitHub release with release notes
  4. CI will automatically publish to PyPI

Questions?

If you have questions about the development process or need help, feel free to open an issue for discussion.

Thank you for contributing to Guard Core!