We appreciate your interest in contributing to Guard Agent. This document provides comprehensive guidelines for participating in the development of this enterprise-grade security telemetry solution, ensuring efficient collaboration and maintaining our high standards of code quality.
This project maintains strict adherence to the Contributor Covenant Code of Conduct. All contributors are expected to uphold these professional standards. Any violations should be reported directly to the project maintainers for immediate review.
Prior to submitting bug reports, conduct a thorough search of existing issues to prevent duplicates. When documenting a bug, provide comprehensive details:
- Utilize precise, descriptive titles that clearly identify the issue
- Document exact reproduction steps with minimal test cases
- Include specific examples, including relevant HTTP requests and payloads
- Articulate observed behavior versus expected behavior with technical precision
- Provide complete error logs, stack traces, and diagnostic information
- Detail your execution environment: operating system, Python version, framework adapter (fastapi-guard / flaskapi-guard / djangoapi-guard / tornadoapi-guard) and its version, and all relevant dependencies
Feature proposals are managed through GitHub's issue tracking system. When submitting enhancement requests:
- Craft concise yet comprehensive titles that encapsulate the feature scope
- Provide detailed technical specifications for the proposed functionality
- Articulate the business value and technical benefits for the Guard ecosystem's user base
- Include practical implementation examples and use case scenarios
- Reference relevant industry standards, competing implementations, or academic research
- Complete all sections of the pull request template comprehensively
- Maintain strict adherence to PEP 8 and project-specific style conventions
- Implement comprehensive test coverage for all new functionality and bug fixes
- Update technical documentation to reflect architectural changes
- Verify full test suite execution without failures or regressions
- Ensure static analysis tools (mypy, ruff) report zero violations
-
Fork the repository and establish a local development clone
-
This project leverages containerization for consistent development environments. Ensure Docker and Docker Compose are properly installed and configured.
-
Utilize the comprehensive Makefile automation for environment initialization:
# Install dependencies using 'uv'
make install
# To stop all containers
make stopThe project maintains compatibility across Python 3.10, 3.11, 3.12, 3.13, and 3.14. Our containerized testing infrastructure ensures consistency across environments:
# 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-testThis project enforces rigorous code quality through:
Prior to pull request submission, validate compliance with all quality standards:
make lint
make fixand
make lint-docs
make fix-docsTechnical documentation is generated using MkDocs with Material theme. To build and preview documentation locally:
make serve-docsComprehensive documentation updates are mandatory for all significant architectural or API modifications.
This project strictly adheres to Semantic Versioning principles.
- Update version in
pyproject.tomlandsetup.py - Update
docs/release-notes.md - Create a new GitHub release with release notes
- CI will automatically publish to PyPI
For technical inquiries regarding the development process or architectural decisions, please initiate a discussion through the issue tracking system.
Your contributions are vital to the continued evolution of Guard Agent's security capabilities.